Вводные комментарии
Каждая программа, подпрограмма или процедура должна начинаться с комментариев, поясняющих, что она делает. Вводные комментарии могут включать следующие пункты:
Назначение программы.
Указания по вызову программы и ее использованию.
Список и назначение основных переменных или массивов.
Указания по вводу-выводу. Список всех файлов.
Список используемых подпрограмм.
Название применяемых математических методов, а также ссылки на литературные источники, где содержится их описание.
Сведения о времени выполнения программы.
Требуемый объем памяти.
Специальные указания оператору.
Сведения об авторе.
Дата написания программы.
Делайте вводные комментарии
Пояснительные комментарии
Пояснениями нужно сопровождать те части программы, которые трудно понять без комментариев. Рекомендуется комментировать каждый логически выделенный кусок программы, а так же циклы и условные операторы.
Сопровождайте комментариями те действия, которые, с вашей точки зрения, могут быть не совсем понятны другому. Эта документация будет всегда находиться вместе с программой и поможет разобраться в ее логике.
Существенно содержание комментариев. Нет необходимости переводить с английского каждый оператор программы. Комментарии должны объяснять цель группы операторов программы, а не перефразировать программу.
/* ПРОВЕРИТЬ, ЯВЛЯЕТСЯ ЛИ ВЕЛИЧИНА ОТРИЦАТЕЛЬНОЙ */
Это плохой комментарий, потому что читающий программу знаком с языком программирования и в состоянии определить, что имеет место такая проверка. Но он не знает, зачем это делается. Предполагается, что именно комментарий должен ответить на этот вопрос. Вместо вышеприведенного бесполезного комментария следовало бы дать такой:
/* ВЫПОЛНИТЬ ОБРАБОТКУ ОТРИЦАТЕЛЬНОГО САЛЬДО (СУММАРНЫЕ РАСХОДЫ ПРЕВЫШАЮТ ДОХОДЫ.) */
Комментарии должны указывать цель действия или объяснять логику программы.
Рекомендуется располагать комментарии на одинаковом уровне, например, начинают комментарии с 50-й позиции. Перед строкой комментариев желательно пропускать пустую строку.
Располагайте комментарии таким образом, чтобы это не делало ее менее наглядной.
Комментарии должны быть правильными. Другими словами, они должны быть правильными сначала и изменяться в соответствии с изменениями программы. Неправильные комментарии - это хуже, чем их отсутствие
Оглавления
Если программа очень большая, то целесообразно использовать оглавление. Оглавление размещается в начале главного модуля программы и должно содержать название, размещение и функцию каждого программного модуля.
Пропуск строк
Пропуск строк делает программу наглядной. Пропуском одной строки можно отделять каждую группу логически связанных операторов, пропуском двух строк - основные логические фрагменты программы.
Пробелы
В языках программирования пробелы довольно часто ставятся произвольно. В изъятии пробелов из программы не больше смысла, чем в том, чтобы их убрать из текста. Что вы скажете, например, о такой фразе:"Явсегдамогунаписатьнечтоподобное,высможетепрочестьно этопотребуетотвасслишкоммногоусилий".
Пробелы следует ставить везде, где это приводит к улучшению читаемости программы.
Можно написать такой оператор:
for(i=1;i<=10;i++)
Но написанный ниже оператор читать значительно легче:
for ( i=1; i<=10; i++)
Ставьте пробелы между элементами списка данных, а также до и после операций +, -, =. Пробелы между операциями *, / не всегда желательны. Пробелы можно использовать для указания приоритета операций. Например, запись вида
1 + А*В
предпочтительнее, чем вводящее в заблуждение выражение
1+А * В
Упорядочение по алфавиту
Упорядочение по алфавиту - одна из предпосылок легкой читаемости программы, второй является аккуратность. Так, списки должны быть организованы в столбцы. Обратите внимание, насколько труднее читать список
int ALPHA,BETA,CHI,DELTA,EPSIL,ETA,GAMMA, IOTA,KAPPA,LAMBDA,MU,NU,OMEGA,
OMICR,PHI,PI,2PSI,RHO.SIGMA.TAU;
по сравнению со следующим:
int ALPHA, BETA, CHI, DELTA, EPSIL, ETA,
GAMMA, IOTA, KAPPA, LAMBDA, MU, NU,
OMEGA, OMICR, PHI, PI, PSI, RHO,
SIGMA, TAU
Тоже самое касается числовых матриц.
В одной строке нежелательно располагать больше одного оператора
Скобки
Правильное использование скобок существенно улучшает удобочитаемость программы. Так как последовательность выполнения операций определяется их приоритетами, то программист зачастую может ограничиться небольшим количеством скобок, но при этом затрудняется чтение и корректировка программы.
Например,
A*B*C/(D*E*E) (A*B*C)/(D*E*F)
A*B/C*D/E*F (A*B*D*F)/(C*E)
Основное правило таково: в сомнительных случаях ставьте скобки - это не только сделает программу более понятной, но и предотвратит ошибки. Часто в логических выражениях скобки используют недостаточно, что приводит к ошибкам.
Скобки обходятся дешевле, чем ошибки.
Отступы от начала строки
Операторы, связанные между собой, рекомендуется располагать на одинаковом расстоянии от начала строки. Такая операция называется - использование параграфов. Отступы, не оказывая влияния на логику программы, но значительно улучшают ее восприятие.
Имена переменных
При составлении имен переменных рекомендуется руководствоваться следующими правилами:
Имя переменной должно соответствовать ее назначению.
Пример. Для расчета площади рекомендуется использовать S, периметра P. Для расчета налога лучше использовать переменную nalog, чем r2.
Имя переменной должно легко читаться.
Пример. Правила языков программирования не запрещают использовать имя sph1z12, однако его трудно произнести и написать, а значит Вам обеспечены ошибки.
Имя переменной не должно быть слишком длинным. Оптимальная длина не должна превышать 6-7 символов.
Если имя состоит из нескольких частей, их рекомендуется отделить.
Пример. Имена PrintOnly или print_only воспринимаются лучше, чем printonly.
Избегайте многозначности.
Пример. Допустим в Вашей программе рассчитывается среднее время и используются дни недели. В этом случае, имя SRED может вызвать путаницу. Не понятно толи речь идет о среде, толи о среднем значении. Лучше использовать такие имена: SREDNEE, SREDA.
Для функций, которые возвращают логические значения, рекомендуется использовать такие имена, чтобы было ясно, как понимать значения истина и ложь.
Пример. Имя PrintOnly лучше, чем имя PrintStatus.
Используйте префиксы в тех языках программирования, в которых это принято.
Например, в Visual FoxPro принято использовать префикс, который указывает на тип переменной: c - символ, n - целое число и т.д.