CHAP2-4 (1018803), страница 2

Просмтор этого файла доступен только зарегистрированным пользователям. Но у нас супер быстрая регистрация: достаточно только электронной почты!

Текст из файла (страница 2)

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

Если вам на самом деле нужна отпечатанная документация высшего качества, то вы можете воспользоваться чем-нибудь похожим на систему Web (для языка Паскаль) или CWeb (для языков С и С++) в комбинации с TeX¹. Я пользуюсь подобной системой под названием arachne, которая была разработана мной для того, чтобы писать свою книгу Compiler Design in C. (Arachne документирует тексты на С и С++, используя в качестве редактора troff). Все эти программы позволяют вам размещать исходный текст программы и документацию в одном файле. Вы можете выделить исходный текст для компиляции, или загрузить этот файл в текстовый процессор, чтобы напечатать единое руководство с исходным текстом и документацией. Эти системы позволяют осуществлять перекрестный поиск идентификаторов в программе и документации, позволяя вам прослеживать связи одной части программы с другой ("этот код используется вон там"), и так далее. Так как для получения печатной версии используется обычный текстовый процессор, то вы можете делать то, чего непросто добиться в комментариях - вставлять рисунки, например.

24. Комментарии должны быть предложениями.

Они должны быть хорошо составлены и иметь правильную пунктуацию, по возможности без сокращений. Не превращайте свои комментарии в секретный код, применяя странные сокращения и изобретая свой собственный грамматический строй. Вам также не должна требоваться нить Ариадны для расшифровки комментариев.

25. Пропустите свой исходный тест через систему проверки орфографии.

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

26. Комментарий не должен подтверждать очевидное.

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

++x; // увеличить x

но мне также не нравятся комментарии типа:

/*-------------------------------------------

* Определения глобальных переменных:

*-------------------------------------------

*/

Любой средний программист знает, как выглядит определение.

27. Комментарий должен предоставлять только нужную для сопровождения информацию.

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

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

Листинг 1. Бесполезный заголовочный комментарий.

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

28. Комментарии должны быть в блоках.

Комментарии в общем воспринимаются лучше, когда помещаются в многострочных блоках, которые чередуются с блоками текста программы. Для этого комментарий должен описывать на высоком уровне, что делают несколько последующих строк кода. Если комментарии попадаются через строчку, то это похоже на чтение двух книг одновременно, причем по строке из каждой по очереди. И если программа, комментируемая вами, сложная, то вы можете воспользоваться сносками:

// Вот блочный комментарий, описывающий последующий блок программы.

// После общего резюме я описываю некоторые особенности:

//

// 1. Этот комментарий описывает, что происходит в строке с меткой 1

//

// 2. Этот комментарий описывает, что происходит в строке с меткой 2

//

Характеристики

Список файлов книги