Заметки об исправлении ошибок

Частая, но спорная практика – помещение заметок в местах, где исправлены ошибки. Посреди какой-нибудь функции можно натолкнуться на комментарий такого типа:

// <ссылка на баг> заменено на метод blah.foo2()

// поскольку blah.foo() некорректно обрабатывал

// <некоторое условие>

blah.foo2();

Написанные с лучшими намерениями (чтобы помочь разобраться в случившемся во время разработки), эти комментарии часто приносят больше вреда, чем пользы. Чтобы понять суть проблемы,вам придется найти ошибку в системе учета ошибок и загрузить предыдущую вер-

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

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

Комментарии должны касаться настоящего, а не прошлого. Не описывайте того, что претер-пело изменения, и не рассказывайте о том, как было раньше.

Устаревание комментариев

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

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

Встретив код в блоке комментариев, вы станете размышлять, как он там оказался. Было ли это неосуществленным исправлением? Или добавлением, не доведенным до конца? Работает ли этот код? Все ли функции реализованы в остальном коде?

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