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

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

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

Увидев предупреждающие флажки типа XXX, отнеситесь к ним со всем вниманием и осторожностью. Следите также за операторами вывода, которые закомментированы. Они явно указывают на то, что в этом месте кода были проблемы; изучите этот код особенно внимательно!

Помните о постепенной деградации комментариев. Если в комментарии сказано, что нечто определено в foo.c, нет никакой уверенности, что так оно и есть до сего дня. Всегда верьте коду и сомневайтесь в комментариях.

Резюме

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

Делмор Шварц

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

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

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

• Стремятся писать малочис- • В комментариях объясняют почему

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

ментарии

• Стараются писать хороший •Не понимают разницы между пло

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

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

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

• В комментариях объясняют как • Пытаются подкрепить плохой код

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

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

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

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