Комментарии
Для удобства чтения программа должна быть хорошо откомен-тирована. Если операторы языка программирования позволяют понять, как работает программа, то комментарии должны пояс- нить что и зачем делают эти операторы.
Иногда утверждают, что комментарии будут вставлены позже. Но через удивительно короткое время авторы программы обнаруживают, что забыли ее многие детали. Программы с пояснительными комментариями значительно легче отлаживать.
Комментарии нужны как на стадиях проектирования и отладки gрограммы, так и позже. Они должны содержать некоторую дополнительную информацию, а не перефразировать программу.
Для структурных программ обычно требуется меньше комментариев, чем для неструктурированных, так как программы пер- вого вида понятнее и в них меньше переходов.
Каждая программа, подпрограмма или процедура (модуль) должна начинаться с блока комментариев (вводных комментариев), поясняющих, что она делает, и может включать нижеперечисленные сведения.
1. Имя программы.
2. Назначение программы. Функции, которые она выполняет.
3. Указания по вызову программы и ее использованию.
4. Список и назначение основных переменных.
5. Ожидаемые входные и выходные данные.
6. Список вызываемых подпрограмм и модулей.
7. Необычные условия или аварийные ситуации, которые могут возникнуть при выполнении программы.
8. Сведения о времени и месте выполнения программы.
9. Требуемый объем памяти, другие ограничения и условия использования.
10. Специальные указания оператору, если это необходимо.
11. Сведения об авторе.
Следующие рекомендации способствуют эффективному документирова-нию внутри программы.
1. Комментарии следует писать в таких местах программы, которые необходимо кому-то пояснить.
2. Комментарии должны быть правильными с самого начала и изменяться в соответствии с изменениями программы. Неправильные комментарии хуже их отсутствия, так как они вводят в заблуждение читателя программы.
3. Комментарии должны содержать некоторую дополнительную информацию, а не перефразировать программу.
4. Комментариев должно быть ровно столько, сколько необходимо. Лишние комментарии — это мусор в программе.
5. В каждом отдельном операторе языка редко проявляются какие-либо действия, и поэтому нет необходимости описывать каждый оператор отдельным комментарием.
6. Комментарии к переменным должны нести информацию об их физических свойствах или функциональном назначении.
7. Комментарии удобно использовать для разделения программы на отдельные подразделы. Такие подразделы содержат обычно от 5 до 10 операторов и имеют одноцелевое назначение.
8. Идентификаторы должны быть мнемоничны, что существенно дополняет комментарии. Необходимо выбирать осмысленные имена. Х=Х+А дает гораздо меньше информации, чем SUMMA=SUMMA+A.
9. В качестве имен переменных должны употребляться термины, используемые в данной области. Необходимо избегать схожих по виду имен, их неестественных написаний и подобных по написанию символов (Х10 и Х10). Числа лучше писать в конце имени.
10. При составлении имени переменной можно следовать определенным соглашениям. Например, переменные целого типа могут начинаться с букв i, j, k, 1, m, n (обычно и общепринято).
11. Для сокращения идентификаторов можно использовать правила, разработанные Микаэлом Джексоном:
а) каждое значащее слово в имени может быть сокращено, но не более трех;
б) в аббревиатуру всегда должны включаться начальные буквы слов;
в) согласные важнее гласных;
г) начало слова важнее его конца;
д) аббревиатура должна включать в себя от 6 до 15 букв.
12. Все выдаваемые программой печати должны быть откомментированы и иметь естественный формат (матрица не печатается в строку и т.д.).
13.Необходимо придерживаться очевидного порядка действия. Например, если надо вычислить
DISKRM:= SQR(B)-4*A*C ;
IF DISKRM > 0 THEN BEGIN
X[l]:= (-B+SQRT(DISKRM)) / (2*A) ;
X[2]:= (-B-SQRT(DISKRM)) / (2*A) ;
END;
Намного понятней, чем
DISKRM: = B*B-4*A*C
IF DISKRM > 0 THEN J: =1 ELSE GO TO 2 ;
1: I:= 2-(J+l)/2 ;
X[I]:= (-B+J*EXP(0.5*LN(X))) / (2*A) ;
J:= -J IF J < 0 THEN GO TO 1 ;
2;----------
Назад
