Закомментированные куски кода и TODO

Когда я вижу в production коде, в котором мне надо по какой-то причине разобраться, что-то типа:

...
int x = (i << 8) | (i >> 2) | ((i & 0x06) ^ 0xAA);

// if (x >= 0x12345)
//  x = x >> 3;

calc_something_complicated(x);
...

мне хочется рвать и метать. Расчехлить blame, найти автора и заглянуть ему в глаза.

Иначе, что мне остается: только думать, что автор этих строк, видимо, бился с формулой, пытался подогнать результат под что-то (возможно, какой-то тест). Достиг ли он результата? Или может оно так и продолжает глючить… Кто знает. Единственное, о чем этот код однозначно говорит, что автор не был уверен в том, что пишет. Потому, что если он был уверен, то удалил бы этот фрагмент или раскомментировал бы его навсегда.

На втором месте у меня стоит отладочная печать, навеки оставленная в коде:

...
int x = (i << 8) | (i >> 2) | ((i & 0x06) ^ 0xAA);

// std::cerr << "На этот раз x = " << x << std::endl;

calc_something_complicated(x);
...

Снова получается, что автор сомневался и так и не отладил все до конца.

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

Ну на третьем месте нашего хит-парада - блоки TODO.

...
int x = (i << 8) | (i >> 2) | ((i & 0x06) ^ 0xAA);

// TODO: Заменить тип int на int64, так как на носу эра 64-разрядных машин.
// Программист Вася, 06.10.2009. Если что, вы знаете где меня искать.

calc_something_complicated(x);
...

Тут еще куда ни шло. Куски TODO можно найти автоматическим поиском при подготовке релиза и перед ответственным слиянием. Но каждый TODO должен быть подписан и датирован, а лучше еще и детально объяснен. Ни что так не помогает оценить “нужность” куска кода, как дата его последней модификации.

Итак, вывод тут только один: в production коде никогда не должно быть закомментированных кусков. А если они есть, то они должны сопровождаться четкими комментариями, поясняющими их суть.


Оригинальный пост | Disclaimer

Комментарии