110 Часть II. Программирование на C++
регламентирующих комментарии и имена, может превзойти объем исходного кода программ. Бывают прецеденты, что комментарии, предшествующие функциям, включают в себя перекрестные ссылки, спецификации функций, планы тестирования и т. д. и распространяются на добрую половину страницы. Большинство из вас, конечно, не сталкивается со столь жесткими стандартами — вам нужны просто несложные в реализации и обеспечивающие единый стиль, читаемость и доступность правила.
Очень простой и широко распространенный среди программистов стандарт связан с популярной библиотекой разработки Zinc Application Framework. Его исключительно просто придерживаться и он обеспечивает ясную и строгую структуру комментариев в вашем тексте. Этот стандарт подразумевает комментирование файлов, функций, переменных и блоков.
Прежде чем приступить к его рассмотрению, примите к сведению, что любые стили комментирования и именования, которым вы будете следовать в своем проекте, должны быть в первую очередь удобны лично вам (вашей группе, отделу, организации). Они могут и должны быть приспособлены под ваши собственные нужды. Соглашения, предлагаемые Zinc* Application Framework — это лишь один из возможных вариантов.
Файлы
Файлы исходного кода и заголовков обычно начинаются блоком комментариев, содержащих название приложения или библиотеки, имя файла и всевозможную сопутствующую информацию об авторских правах. Например, если вышеприведенная функция является частью приложения под названием "Bibliographies-R-Us" и содержится в файле Convert.cpp, соответствующий блок комментариев может выглядеть так:
// Bibliographies-R-Us - CONVERT.CPP
// COPYRIGHT © 1995-1996. All Rights Reserved.
// Macmillan Computer Publishing. Indianapolis, Indiana USA
Блок комментариев такого типа открывает каждый файл исходного текста и заголовков в проекте, предоставляя исчерпывающую информацию о владельцах файла, а также служит неплохим заголовком при печати. Если вам требуется дополнительная информация, например имя ответственного разработчика, просто добавьте одну-две строки.
Функции
В большинстве систем комментирования функциям и функциям-членам предшествует блок комментариев, кратко поясняющих назначение соответствующей функции и описывающих ее входные и выходные параметры. Постарайтесь делать их сжатыми и точными.