Правила программирования на С и С++. Главы 1-6
Страница 27. Располагайте программу и документацию вместе

23. Располагайте программу и документацию вместе.

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

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