Комментарии в программе

Создать форматированные документы из комментариев и объявлений в исходном тексте довольно просто, но вначале нужно убедиться, в тексте программы действительно есть комментарии. Программа должна иметь комментарии, но слишком большое их количество может быть так же плохо, как и малое.

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

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

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

Имена переменных должны выбираться четко и со смыслом. Например, имя foo, не имеет смысла, так же как doit или manager, или stuff. «Венгерский» стиль именования (в котором вы кодируете информацию о типе переменной в самом ее имени) крайне нежелателен в объектно-ориентированных системах. Не забывайте, что вы (и те, кто идет за вами) будут читать текст программы много сотен раз, но писать ее будут лишь несколько раз. Не торопитесь, и напишите connectionPool вместо ср.

Имена, вводящие в заблуждение, еще хуже, чем бессмысленные. Приходилось ли вам слышать, как кто-нибудь объясняет несоответствия в унаследованном тексте программы типа: Подпрограмма с именем getData на самом деле записывает данные на диск? Человеческий мозг будет периодически все путать – это называется эффектом Струпа [Str35]. Вы можете поставить на себе следующий эксперимент, чтобы увидеть эффект подобных помех. Возьмите несколько цветных ручек и напишите ими названия цветов спектра. Но при этом название цвета должно быть написано только ручкой другого цвета. Вы может написать слово «синий» зеленым цветом, слово «коричневый» – красным и т. д. (В качестве альтернативы имеется набор цветов спектра, уже помещенный на наш web-сайт www.pragmaticprogrammer.com.) Как только вы написали названия цветов, постарайтесь как можно быстрее произнести вслух название цвета, которым написано каждое слово. В определенный момент вы собьетесь и станете читать названия цветов, а не сами цвета. Имена очень важны для восприятия, а имена, вводящие в заблуждение, вносят беспорядок в программу.

Вы можете документировать параметры, но задайте себе вопрос, а нужно ли это делать во всех случаях. Уровень комментариев, предлагаемый средством JavaDoc, кажется весьма приемлемым:

/**

* Найти пиковое (наивысшее) значение в указанном интервале дат

* @param aRange Range of dates to search for data.

* @param aThreshold Minimum value to consider.

* @return the value, or codenullcode if no value found

* greater than or equal to the threshold.

*/

public Sample findPeak(Date Range aRange, double aThreshold);

Comment Out #2 / Настя Ивлеева х Саша Гудков


Читать еще…

Понравилась статья? Поделиться с друзьями: