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


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


Подобно дорожным знакам на улицах Нью-Йорка, говорящим "Даже и не думайте здесь парковаться!", знаки на входе в отдел программистов должны предупреждать " Даже и не думайте написать подпрограмму без заголовочного комментария". Этот комментарий, следующий сразу за ключевым словом is, кратко формулирует цель программы; он сохраняется в краткой и плоской краткой форме класса:

distance_to_origin: REAL is -- Расстояние до точки (0, 0) local origin: POINT do create origin Result := distance (origin) end

Обратите внимание на отступ: комментарий начинается на шаг правее тела подпрограммы.

Комментарий к заголовку должен быть информативным, кратким, ясным. Он имеет собственный стиль, которому будем обучаться на примере, начав вначале с несовершенного комментария, а затем улучшая его шаг за шагом. В классе CIRCLE к одному из запросов возможен такой комментарий:

tangent_from (p: POINT): LINE is -- Возвращает касательную линию к текущей -- окружности, -- проходящую через данную точку p, -- если эта точка лежит вне текущей окружности require outside_circle: not has (p) ...

В стиле этого комментария много ошибок. Во-первых, он не должен начинаться "Возвращает ..." или "Вычисляет ... ", используя глагольные формы, поскольку это противоречит принципу Разделения Команд и Запросов. Имя, возвращаемое не булевым запросом, типично использует квалифицированное существительное. Поэтому лучше написать так:

-- Касательная линия к текущей окружности, -- проходящая через данную точку p, -- если эта точка лежит вне текущей окружности

Так как комментарий теперь не предложение, а просто квалифицированное имя, то точку в конце ставить не надо. Теперь следует избавиться от дополнительных слов (в английском особенно от the), не требуемых для понимания. Для комментариев желателен телеграфный стиль. (Помните, что читатели, любящие литературные красоты, могут выбрать для чтения романы Марселя Пруста.)

-- Касательная линия к текущей окружности, -- проходящая через точку p, -- если точка вне текущей окружности

Следующая ошибка содержится в последней строчке.


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



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