зачастую путают хорошее комментирование и многословное . Согласитесь, комментарии вида:

i = 10; Присваиваем значение 10 переменной i выглядят диковато. Тем не менее, их очень просто расставлять и, поэтому, этим часто злоупотребляют. Хороший комментарий не должен находится внутри основного текста подпрограммы. Комментарий должен располагаться перед заголовком функции; пояснять что и как делает подпрограмма, какие условия накладываются на входные данные и что от нее можно ожидать; визуально отделять тела функций друг от друга. Потому что при просмотре текста программы зачастую незаметно, где заканчивается одна и начинается другая подпрограмма. Желательно оформлять такие комментарии подобным образом:

/**********************************************

* function

void function()

Этот комментарий можно использовать в любом случае, даже если из названия подпрограммы понятно, что она делает - продублировать ее название не тяжелый труд. Единственное, из опыта следует, что не надо переводить название функции на русский язык; если уж писать комментарий, то он должен что-то добавлять к имеющейся информации. А так видно, что комментарий выполняет декоративную роль.

Чем короче функция, тем лучше. Законченный кусочек программы, который и оформлен в виде независимого кода, значительно легче воспринимается, чем если бы он был внутри другой функции. Кроме того, всегда есть такая возможность, что этот коротенький кусочек потребуется в другом месте, а когда это требуется, программисты обычно поступают методом cut&paste, результаты которого очень трудно поддаются изменениям.

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

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

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

* Комментарий */

Тогда он смотрится не как обычный текст, а именно как нужное пояснение.

Остальной текст, который желательно не комментировать, должен быть понятным. Названия переменных должны отображать их сущность и, по возможности, быть выполнены в едином стиле. Не надо считать, что короткое имя лучше чем длинное; если из названия короткого не следует сразу его смысл, то это имя следует изменить на более длинное. Кроме того, для C++ обычно используют области видимости дя создания более понятных имен. Например, dictionary::Creator и index::Creator: внутри области видимости можно использовать просто Creator (что тоже достаточно удобно, потому что в коде, который имеет отношение к словарю и так ясно, какой Creator может быть без префикса), а снаружи используется нужный префикс, по которому смысл имени становится понятным.

Кроме того, должны быть очень подробно прокомментированы интерфейсы. Иерархии классов должны быть широкими, а не глубокими. Все дело в подходе: вы описываете интерфейс, которому должны удовлетворять объекты, а после этого реализуете конкретные виды этих объектов. Обычно все, что видит пользователь - это только определение базового класса такой широкой иерархии классов, поэтому оно должно быть максимально понятно для него. Кстати, именно для

возврата объектов, удовлетворяющих определенным интерфейсам, используют умные указатели.

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

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

Следовательно, надо предоставить читателю возможность отвлеченного ознакомления с кодом. Под этим подразумевается возможность удобного листания комментариев или распечаток программной документации. Подобную возможность обеспечивают программы автоматизации создания программной документации. Таких программ достаточно много, для Java, например, существует JavaDoc, для C++ - doc++ и doxygen. Все они позволяют сделать по специального вида комментариям качественную документацию с большим количеством перекрестных ссылок и индексов.

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

Это предполагает, что вы сначала пишите документацию, а потом по ней строите исходный текст. Такой подход называется литературным программированием и автором данной концепции является сам Дональд Кнут (тот самый, который написал Искусство программирования и сделал TeX). У него даже есть программа, которая автоматизирует этот процесс, она