Самодокументуемость программы
Важным моментом хорошего стиля программирования является наличие комментариев (заключаются в {}).Комментарии применяются в следующих случаях:
- — Описание спецификации программы или модуля.
- — Описание спецификации функции.
- — Описание назначения идентификатора.
Спецификация программы или Модуля
Любая программа или модуль должны начинаться с спецификации, в которой должна быть отражена следующая информация:
- — Имя программы.
- — Автор.
- — Среда разработки.
- — Дата создания.
- — Дата последней модификации.
- — Краткое описание программы
Пример:
{*********************************************
* Hello. pas *
* Лабораторная работа №1 *
*********************************************
* Гармаш Д. В. *
* Garmash@ukr. net *
* Начало разработки — 3 сентября 2007*
* Последняя смена — 15 октября 2007 *
* Pascal *
*********************************************}
Спецификация Функции
Спецификацию удобнее располагать перед самой функцией в случае, если она необходима. Спецификацию функции применяют, если неочевидно логику функции или ее параметры, или возвращаемого значения. Неочевидность должна компенсироваться спецификацией.
Например:
(* ================================================ ===
Функция DayOfWeek
Возвращает день недели дать D / M / Y;
Год Y должен быть в отрезке 1582..4902;
Результат: ВСК = 0, ПНД = 1, ВТР = 2 … СБТ = 6
================================================== == *)
Function DayOfWeek (D, M, Y: integer): byte;
Begin
…
End;
Описание Идентификатора
Комментировать идентификатор необходимо, если его содержание не следует из названия, а также, если это не переменная цикла. Комментарий в этом случае обычно располагают справа от описания идентификатора.
Напрмер:
Var D: integer; {День недели}
Лесенка
«Лесенка» должна отражать структурную вложенность языковых конструкций. Рекомендуется отступление не менее 2-х и не более 8-и пробелов. Принятого отступления нужно соблюдать во всем тексте программы.
Например:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
S: = ; For i: = to 10 do if (i mod 2 = ) then writeln ( 'Парное'); else begin writeln ( 'Нечетное'); S = S + и end; Writeln ( 'Сумма нечетных =', S) |
Использование комментариев в тексте Программы
Комментарий — это пояснительный текст, игнорируются компилятором. Комментарий должен быть заключен в «скобки», определяющие начало и конец — {и} или (* и *).
При всей очевидности пользы комментариев их далеко не всегда включают в программу во время ее написания. Комментарии опускают в целях экономии времени, предполагая вставить их затем в готовую программу. Если программа более-менее сложная, то через достаточно короткое время автор убеждается, что забыл какие-то ее детали. И тут «экономия» времени оборачивается его потерей.
Программы с комментариями значительно легче налаживаются, не говоря уже о том, что с ними легче знакомятся другие люди.
Комментарии могут заменить как одну строку, так и более:
{Комментарии к программе}
(Параметры функции DayOfWeek.
D — день месяца. Целое в диапазоне 1-31
M — месяц года. Целое в диапазоне 1-12
Y — год. Целое в диапазоне 1900-2099
*)
Неправильное определение Комментариев
Внутри набора символов, является комментарием, не должно быть символов определяющий начало и конец комментария, соответственно {и} или (* и *).
{Комментарии к алгоритму {решения краевой задачи}}
или
(* Комментарии к алгоритму решения *) краевой задачи *)
В то же время, вложения «скобок» различных типов допустим, хотя и не имеет смысла:
{Комментарии к алгоритму (* решение краевой задачи *)}
(* Комментарии к алгоритму {решения краевой задачи} *
Резюме. Правила хорошего Тона
- 1. Создавайте код, который легко читать.
- 2. Добавляйте комментарии везде, где это возможно.
- 3. Выбирайте правильные, имена переменных., Которые о чем-то «говорят»
- 4. Создавайте ясные и согласованные интерфейсы.
- 5. Делите код на логические функциональные блоки.
- 6. Делайте отдельные части кода независимыми.
- 7. Для группировки функций (не только логической, но и физической) используйте отдельные файлы.
- 8. Пишите документацию.