Подсказка 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 <code>null<code> if no value found
* greater than or equal to the threshold.
*/
public Sample findPeak(Date Range aRange, double aThreshold);
Вот перечень того, чего не должно быть в комментариях к исходному тексту программы.
• Перечень функций, экспортируемых программой в файл. Существуют программы, которые анализируют исходный текст. Воспользуйтесь ими, и этот перечень никогда не устареет.
• Хронология изменений. Для этого предназначены системы управления исходным текстом программы (см. "Управление исходным текстом"). Однако, будет полезно включить информацию о дате последнего изменения и сотруднике, который внес это изменение [52].
• Список файлов, используемых данным файлом. Это можно более точно определить при помощи автоматических инструментальных средств.
• Имя файла. Если оно должно указываться в файле, не поддерживайте его вручную. Система RCS и ей подобные могут обновлять эту информацию автоматически. При перемещении и удалении файла вам не хочется вспоминать о необходимости редактирования заголовка.
Одним из наиболее важных фрагментов информации, который обязан появиться в исходном файле, – это имя автора, не обязательно того, кто осуществлял последнюю редакцию, но имя владельца. Приложение обязательств и ответственности к исходному тексту программы творит чудеса, сохраняя людей честными (см. "Гордость и предубеждение").
Проект также может потребовать наличия определенных ссылок на авторские права или других юридических стереотипов в каждом исходном файле. Сделайте так, чтобы программа редактирования вставляла эти элементы автоматически.
При наличии обширных комментариев инструментальные средства, подобные JavaDoc [URL 7] и DOC++ [URL 21], могут извлекать и форматировать их для автоматического создания документации на уровне API. Это является одним из конкретных примеров более универсальной методики, которой мы пользуемся, – исполняемые документы.
Исполняемые документы
Предположим, что есть спецификация, которая перечисляет столбцы в таблице базы данных. Тогда мы получим отдельный набор команд SQL для создания реальной таблицы в базе данных и, по всей вероятности, некую структуру записи на языке программирования для хранения содержимого строки в таблице. Одна и та же информация повторяется три раза. Стоит изменить один из этих трех источников – и два других немедленно устареют. Это явное нарушение принципа DRY.
Для решения этой проблемы необходимо выбрать авторитетный источник информации. Это может быть спецификация, инструментальное средство для построения схем баз данных или некий третий источник. Выберем в качестве источника спецификацию. Теперь она является моделью нашего процесса. Нам необходим способ экспортирования информации, содержащейся в ней, в виде различных визуальных представлений, например, в виде схемы базы данных и записи на языке программирования высокого уровня [53].
Если документ хранится в виде простого текста вместе с командами описания документов (например, в виде HTML, LATeX. или troff), то в этом случае можно использовать такие инструментальные средства, как Perl, для извлечения схемы и ее автоматического переформатирования. Если документ хранится в двоичном формате текстового процессора, то ознакомьтесь с некоторыми вариантами действий, приведенных во врезке, данной ниже.
Теперь документ – неотъемлемая часть разработки проекта. Единственным способом изменения схемы является изменение документа. Вы гарантируете, что спецификация, схема и программа находятся в согласии. Вы сводите к минимум работу, которую необходимо выполнить для внесения каждого изменения, и можете обновлять визуальные представления изменений автоматически.
К сожалению, в настоящее время все больше проектной документации составляется с помощью текстовых процессоров, сохраняющих файл на диске в некоем определенном формате. Мы говорим "к сожалению", потому что это существенно ограничивает возможности автоматической обработки документа. Но у вас в запасе имеется еще два варианта: