128 Глава 5. Заметки на полях

первоначальная стройность замысла. Однако комментарии деградиру%

ют, по%видимому, значительно быстрее, чем остальной код. Они устаре%

вают вместе с кодом, который объясняют. Это может сильно досадить.

Простое решение может быть таким: если вы исправляете, добавляете

или модифицируете любой код, исправьте, добавьте и модифицируйте

все комментарии, которые к нему относятся. Не ограничивайтесь изме%

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

приводили к появлению ложных комментариев. Следствие: коммента%

рии нужно писать так, чтобы их было легко обновлять, иначе их не бу%

дут обновлять. Комментарии должны быть четко связаны с разделом

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

Если вы изменили код, проверьте правильность комментариев, находящихся

рядом с ним.

Еще одна скверная привычка – сохранение закомментированных бло%

ков кода. Они станут источником путаницы, когда вы обратитесь

к своему коду год спустя или когда им займется другой программист.

Встретив код в блоке комментариев, вы станете размышлять, как он

там оказался. Было ли это неосуществленным исправлением? Или до%

бавлением, не доведенным до конца? Работает ли этот код? Все ли

функции реализованы в остальном коде?

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

удалите его вообще – если понадобится, вы всегда найдете его в систе%

ме управления версиями. Даже если вы считаете, что отключаете

фрагмент кода временно, сделайте себе пометку, иначе вы можете за%

быть довести дело до конца.

Сопровождение и бессодержательные комментарии

Работая над старым кодом, лучше всего сохранить в нем любые дурац%

кие комментарии, если только они не несут явного вреда. Пусть они

останутся как предупреждение тем, кто будет сопровождать этот код

когда%нибудь в будущем – полезное свидетельство качества соответст%

Случай из жизни

Однажды я работал над фрагментом кода, где был комментарий,

извещавший о том, что функции A и B пока не реализованы. Обе

они были мне нужны, поэтому я написал их реализацию. После

этого я узнал, что функция B уже реализована, а функция A бы%

ла не нужна, поскольку реализация B решала и ее задачу. Если

бы написавший ее программист убрал свой ошибочный коммен%

тарий, я не потратил бы столько времени на лишнюю работу.

Резюме 129

вующего кода (точнее, его отсутствия). Конечно, если вы действитель%

но хотите повысить качество этого кода, то и комментарии нужно под%

вергнуть переработке. Обнаружив комментарий, содержащий невер%

ные сведения или ошибки, вы должны переписать его в процессе со%

провождения данного кода.

Увидев предупреждающие флажки типа XXX, отнеситесь к ним со всем

вниманием и осторожностью. Следите также за операторами вывода,

которые закомментированы. Они явно указывают на то, что в этом мес%

те кода были проблемы; изучите этот код особенно внимательно!

Помните о постепенной деградации комментариев. Если в коммента%

рии сказано, что нечто определено в foo.c, нет никакой уверенности,

что так оно и есть до сего дня. Всегда верьте коду и сомневайтесь в ком%

ментариях.

Резюме

Главное – описать увиденное так, чтобы больше не повторяться.

Делмор Шварц

Мы пишем много комментариев. Это вызвано тем, что мы пишем мно%

го кода. Важно научиться писать правильные комментарии, иначе

наш код может потонуть под грузом бестолковых или устаревших

комментариев.

Не нужно переоценивать значение комментариев; благодаря хорошим

комментариям плохой код лучше не станет. Целью должно быть напи%

сание самодокументируемого кода, для которого не требуются ника%

кие комментарии.

Хорошие программисты… Плохие программисты…

• Стремятся писать малочис#

ленные, но добротные ком%

ментарии

• В комментариях объясняют

почему

• Стараются писать хороший

код, а не уйму комментариев

• Пишут полезные и разумные

комментарии

• Не понимают разницы между пло%

хими и хорошими комментариями

• В комментариях объясняют как

• Пишут комментарии, не понятные

никому, кроме них самих

• Пытаются подкрепить плохой код

многочисленностью комментариев

• Помещают в исходные тексты

лишнюю информацию (типа исто%

рии версий и т. д.)