Основы объектно-ориентированного проектирования


Комментарии в заголовках: упражнение на сокращение - часть 3


Несколько общих замечаний. Отметим бесполезность в запросах фраз типа "Возвращает ...", других шумовых слов и фраз, которые следует избегать во всех подпрограммах: "Эта подпрограмма вычисляет (возвращает) ...", просто скажите, что делается. Вместо:

-- Эта программа записывает последний исходящий звонок

пишите

-- Записать исходящий звонок

Как показывает это пример, комментарий к командам (процедурам) должен быть в императивной или инфинитивной форме (в английском это одно и тоже). Он должен иметь стиль приказа и оканчиваться точкой. Для булевых запросов комментарий всегда должен быть в вопросительной форме и заканчиваться знаком вопроса:

has (v: G): BOOLEAN is -- Появляется ли v в списке? ...

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

-- Появляется ли 'v' в списке?

Инструментарий, генерирующий краткую форму класса, использует это соглашение для обнаружения ссылок на сущности.

Нужно следить за согласованностью. Если функция класса имеет комментарий: "Длина строки", в другой процедуре не должна идти речь о "ширине" строки: "Изменить ширину строки", когда речь идет об одном и том же свойстве строки.

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

count: INTEGER -- Число студентов на курсе

Для закрытых атрибутов комментарии желательны, но требования к ним менее строгие.




Начало  Назад  Вперед



Книжный магазин