Глава 5. Соглашения об именах и комментариях_____________________773

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

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

Конечно, количество комментариев — личное дело каждого программиста. Однако если вам нужны некоторые наставления, как сделать ваши комментарии емкими, выразительными и уместными, то прислушайтесь к советам Бъярна Страуструпа, создателя C++.

• Избегайте избыточных комментариев. Если идея ясна из кода программы, не надо добавлять лишних слов. Например, если у вас есть переменная-счетчик wordCount, то совершенно излишне объяснять, что

wordCount++; // инкремент текущего счетчика слов

Если вы программируете на С или C++, то wordCount++ само по себе является достаточным комментарием. При виде выражения wordCount++ в голову сразу приходит "инкремент текущего счетчика слов" — и более ничего не нужно (word — слово, count — счетчик). В этом случае комментарий в перспективе только осложнит сопровождение. К этой проблеме мы еще вернемся ближе к концу главы при обсуждении самодокументируемого кода.

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

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