Язык паскаль онлайн

Самодокументуемость программы

Важным моментом хорошего стиля программирования является наличие комментариев (заключаются в {}).Комментарии применяются в следующих случаях:

• — Описание спецификации программы или модуля.
• — Описание спецификации функции.
• — Описание назначения идентификатора.

Спецификация программы или Модуля

Любая программа или модуль должны начинаться с спецификации, в которой должна быть отражена следующая информация:

• — Имя программы.
• — Автор.
• — Среда разработки.
• — Дата создания.
• — Дата последней модификации.
• — Краткое описание программы

Пример:

{*********************************************

* 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-и пробелов. Принятого отступления нужно соблюдать во всем тексте программы.

Например:

Использование комментариев в тексте Программы

Комментарий — это пояснительный текст, игнорируются компилятором. Комментарий должен быть заключен в «скобки», определяющие начало и конец — {и} или (* и *).

При всей очевидности пользы комментариев их далеко не всегда включают в программу во время ее написания. Комментарии опускают в целях экономии времени, предполагая вставить их затем в готовую программу. Если программа более-менее сложная, то через достаточно короткое время автор убеждается, что забыл какие-то ее детали. И тут «экономия» времени оборачивается его потерей.

Программы с комментариями значительно легче налаживаются, не говоря уже о том, что с ними легче знакомятся другие люди.

Комментарии могут заменить как одну строку, так и более:

{Комментарии к программе}

(Параметры функции DayOfWeek.

D — день месяца. Целое в диапазоне 1-31

M — месяц года.  Целое в диапазоне 1-12

Y — год.  Целое в диапазоне 1900-2099

*)

Неправильное определение Комментариев

Внутри набора символов, является комментарием, не должно быть символов определяющий начало и конец комментария, соответственно {и} или (* и *).

{Комментарии к алгоритму {решения краевой задачи}}

или

(* Комментарии к алгоритму решения *) краевой задачи *)

В то же время, вложения «скобок» различных типов допустим, хотя и не имеет смысла:

{Комментарии к алгоритму (* решение краевой задачи *)}

(* Комментарии к алгоритму {решения краевой задачи} *

Резюме. Правила хорошего Тона

1. 1. Создавайте код, который легко читать.
2. 2. Добавляйте комментарии везде, где это возможно.
3. 3. Выбирайте правильные, имена переменных., Которые о чем-то «говорят»
4. 4. Создавайте ясные и согласованные интерфейсы.
5. 5. Делите код на логические функциональные блоки.
6. 6. Делайте отдельные части кода независимыми.
7. 7. Для группировки функций (не только логической, но и физической) используйте отдельные файлы.
8. 8. Пишите документацию.