Программист-прагматик. Путь от подмастерья к мастеру

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

Эти мысли не отличаются оригинальностью и новизной; идея о брачном союзе программы и документации к ней появляется уже в работе Доналда Кнута о грамотном программировании и в утилите JavaDoc фирмы Sun. Мы хотим уменьшить противоречие между программой и документацией и вместо этого считать их двумя визуальными представлениями одной и той же модели (см. "Всего лишь визуальное представление"). На самом деле мы хотим пойти немножко дальше и применить все наши прагматические принципы к документации так, как мы применяем их к программам.

Подсказка 67: Считайте естественный язык одним из языков программирования

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

Подсказка 68: Встраивайте документацию в проект, а не накручивайте ее сверху

Начнем с внутренней документации.

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

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

В общем, комментарии должны обсуждать, почему выполняется та или иная операция, ее задачу и ее цель. Программа всегда демонстрирует, как это делается, поэтому комментирование – избыточная информация и нарушение принципа 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 null if no value found

* greater than or equal to the threshold.

*/

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

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