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

СодержаниеГлава 8 Прагматические проекты 44 Все эти сочинения Комментарии в программе → Часть 2

Глава 125

Часть 2

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

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

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

* @param aThreshold Minimum value to consider. www.o-gamebox.ru

* @return the value, or codenullcode 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. Это является одним из конкретных примеров более универсальной методики, которой мы пользуемся,  – исполняемые документы.

Навигация

[ Часть 2. Глава 125. ]
Hosted by uCoz