Плаксин М.А.

mapl@psu.ru

ПРАВИЛА ОФОРМЛЕНИЯ ПРОГРАММ

При обучении программированию существует противоречие: будущих профессиональных программистов надо учить писать большие программы, но поскольку сейчас студенты программировать не умеют, их можно учить только на маленьких программах.

Многие требования, естественные для больших программ, для маленьких программ кажутся (а иногда и действительно являются) ненужными. Но, несмотря на это, указанные требования придется соблюдать.

(Большие программы разрабатываются в течение длительного времени. С ними работает большой коллектив программистов. Эти программы долго эксплуатируются и переделываются. Маленькие – учебные – программы разрабатываются один человеком за короткий срок и сразу выбрасываются).

Я еще раз обращаю внимание коллег-студентов, что результатом их трудов по разработке учебных программ являются вовсе не эти написанные ими программы. Эти программы никому не нужны! Результатом их трудов являются те знания, умения и навыки, которые они получили в процессе разработки этих учебных программ.

При работе над программой существует противоречие, связанное с противоположностью операций записи/чтения. При написании программы хочется, чтобы запись была более короткой. При чтении программы хочется, чтобы текст был более расшифрованным. Поскольку пишут программу один раз, а читают – много, это противоречие имеет смысл разрешить в пользу чтения. Лучше один раз потратить усилия на написание, чем много раз тратить их на чтение неразборчивого текста.

ТРЕБОВАНИЯ К ОФОРМЛЕНИЮ ПРОГРАММЫ

Переменные. Имена (идентификаторы)

1. Любая переменная должна использоваться в одном единственном смысле. Должно соблюдаться жесткое правило: разные смыслы – разные переменные. Современные компьютеры обладают достаточным объемом памяти, чтобы не экономить на спичках, используя одну и ту же переменную в нескольких смыслах.

2. Смысл переменной д.б. отражен в ее имени (идентификаторе).

3. Имя должно содержать не менее 3 символов: tek, max, sum, LenLine.

4. Имя не должно совпадать по написанию или звучанию с другими именами (Ol и OI, max и maks, fon и phone) и служебными словами (than, programs).

5. Следует избегать комбинации трудноразличимых символов o/0 (буква «о» и нуль), 1/I/l (единица, латинские буквы «и» и «л»): a01 – ao1, I1 – l1.

6. Для обозначения групп взаимосвязанных переменных удобно использовать префиксы и/или постфиксы: TekStud, TekGroup, MaxStud, MaxGroup.

7. Внутри «сложного» имени, состоящего из нескольких частей, удобно использовать большие буквы: TekStud, TekGroup. Для Паскаля большие и маленькие буквы равноправны, а читать так легче.

8. Вместо больших букв можно использовать подчерки. Они просты для записи и узнаваемы. Но имена с подчерками труднее произносить: tek_stud – «тек подчерк студ».

9. Удобно использовать стандартные обозначения, которые будут одинаковыми во всех программах. Это экономит усилия как при написании (не надо придумывать новые), так и при чтении (сразу понятен смысл обозначений). Например, счетчик цикла всегда начинается с буквы “k”, количество чего-то – с буквы “n”. Тогда смысл переменных kStud, nStud, kGroup, nGroup ясен сразу.

10. По традиции имена типов начинаются с буквы «Т большое»: Tstud, TGroup.

Комментарии

11. Комментарии д.б. трех видов: вступительные (начальные), комментарии к данным, комментарии к алгоритму.

12. В начальных комментариях м.б. указаны решаемая задача, реализуемый алгоритм, требования к ресурсам, автор, время написания и пр.

13. Комментарии к данным поясняют смысл каждой описанной в программе переменной (независимо от мнемоничности ее идентификатора).

14. Комментарии к данным удобно выравнивать по вертикали, чтобы они начинались с одной позиции:

var Tek: real; {текущий элемент последовательности }

LenLine: integer; {длина строки}

15. Комментировать необходимо как локальные данные, так и формальные параметры.

16. В качестве комментариев к алгоритму удобно записывать план программы. составленный при нисходящем программировании. Детализация плана записывается с отступом.

{начать}

{загрузить БД}

Assign(f,’f.dat’);

Reset(f);

{установить параметры отображения БД}

LenLine:= 60;

Razdelit:= ‘*’;

{инициализировать переменные}

sum:= 0;

proizv:= 1;

{продолжить}

{провести поиск информации}

{провести расчеты}

{закончить}

{распечатать результаты}

{сохранить БД}

17. В виде комментария удобно записывать смысл (цель) конструкции (сформулированный при нисходящем программировании). Тогда не придется восстанавливать его из программного текста и можно будет проверить правильность программы. Например:

while {не конец набора данных}

k <= N do

18. Кроме того полезно комментировать все принимаемые в программе решения, неочевидные моменты и пр. Представьте себе, что Вам придется читать эту программу через год, переписывать ее на другой язык, увеличить размер данных в 100 раз и т.п. Какие места в программе полезно прокомментировать в этом случае?

19. Ориентир для количества комментариев: строки с комментариями должны составлять не менее трети строк в программе.

20. Логические части программы удобно отделять друг от друга пустыми строками и/или строками с разделителями. Например, перед каждой процедурой имеет смысл оставлять пустую строку. Группы взаимосвязанных процедур можно отчеркивать строкой-комментарием, состоящей из минусов. Количество пустых строк между частями программы зависит от размера программы (чем программа больше, тем больше пустых строк).

21. Имя процедуры можно подчеркнуть. Для этого потребуется строка-комментарий.

22. В этой же строке м. дать краткое описание смысла процедуры.

23. После завершающего end’а процедуры полезно в комментарии повторить ее имя.

procedure SredBall(…);

{ -------- Подсчет среднего балла за сессию} …

end; {SredBall}

Операторы

24. Восприятие алгоритма очень существенно зависит от того, можно ли охватить его одним взглядом или требуется листание текста. Если сравнить время на разработку двух процедур, таких что алгоритм первой целиком помещается на экране, а алгоритм второй превышает экран на несколько строк, то окажется, что время, требуемое на вторую процедуру, в разы превышает время, требуемое на первую. Необходимость листания резко усложняет восприятие и замедляет работу. Поэтому надо стремиться к тому, чтобы операторная часть процедуры целиком размещалась на экране. Эта идея может потребовать некоторого смягчения некоторых требований, приведенных далее.

25. Исходя из вышесказанного, begin и end процедуры должны размещаться на одном экране.

26. Тогда это же требование автоматически будет касаться всех операторов процедуры.

27. Если процедура не помещается на одном экране, проверьте, м.б. надо поделить ее на несколько процедур?

28. Если разместить процедуру на одном экране не получается, побеспокойтесь о том, чтобы за экран выходили только независимые части, исполняемые однократно. Например, инициализация данных и/или распечатка результатов. Недопустимо, когда листание требуется для многократно просматриваемой части программы, типа тела цикла.

29. Тело цикла обязательно должно целиком помещаться на экране.

30. Каждый оператор лучше начинать в своей строке.

31. В случае если это позволит разместить весь раздел операторов процедуры на одном экране, можно разместить несколько простых операторов в одной строке. Но при этом надо позаботиться о том, чтобы один оператор достаточно хорошо отделить от другого. Например, с помощью трех пробелов.

tek:= tek + step; sum:= sum + tek;

32. Для выделения вложенности конструкций (как операторов, так и данных) следует использовать абзацные отступы.

If tek > max then

max:= tek

else if tek < min then

min:= tek;

record

name: string;

age: 0..100;

end;

33. Размер отступа – 3 позиции. Этого обеспечивает хорошую читабельность программы.

34. Все абзацные отступы в программе должны быть одинаковыми.

35. В условном операторе лучше всегда писать часть else, даже если на этой ветке ничего не делается. Лучше так явно и указать:

If C1 then S1

else {ничего}

36. В условном операторе слово else выравнивать по слову if. Примеры см. выше.

37. В случае вложенных условных операторов выравнивать все ветви по одному уровню (т.е. применять предыдущее правило):

if С1 then S1

else if C2 then S2

else if C3 then S3

else S4

38. В операторе ветвления слово end выравнивать по слову case. Варианты записывать с отступом с одного и того же уровня:

case color of

red: S1;

green, blue: S2;

else S3

end

39. В случае использования операторных скобок begin-end необходимо помнить следующее. Запись составного оператора сама по себе – не самоцель. Запись составного оператора – всего лишь вынужденная мера, обусловленная несовершенством синтаксиса ЯП Паскаль. Было бы гораздо удобнее, если бы в любой позиции, где м. стоять один оператор, могла стоять и последовательность операторов. Увы! В Паскале это не так. Пережитки 1968 г. Но даже тогда синтаксис мог бы быть и получше. Отсюда – идея: операторные скобки следует размещать так, чтобы они не затуманивали смысл объемлющей конструкции, а проясняли его. Т.е. end д. закрывать не begin, а открывающую скобку соответствующего структурного оператора.

40. Для условных операторов операторные скобки располагать так:

if C1 then begin

s1;

s2;

s3

end

else begin

s4;

s5

end {if С1}

41. Для цикла с предусловием операторные скобки располагать так:

while a > b do begin

s1;

s2;

s3;

end; {while a > b }

42. Для цикла со счетчиком операторные скобки располагать так:

for k:= m to n do begin

S1;

S2;

S3

end; {for k}

43. После закрывающей операторной скобки полезно писать комментарий, указывающий, какую именно конструкцию закрывает данная скобка. Примеры см. выше для условного оператора и циклов.

44. Следует помнить, что в операторной части точка с запятой служит разделителем операторов. Т.е. если Вы ставите точку с запятой и после нее ничего не пишете, тем самым Вы вставляете после этой точки с запятой пустой оператор. В некоторых случаях это возможно (например, перед end). В некоторых – нет (например перед else).

begin

S1;

s2; {здесь вставлен пустой оператор}

end

if c1 then

s1;

{здесь вставлен пустой оператор, что недопустимо}

else …