Comments 6
Полезно, интересно. Добавлю в закладки. Буду иногда перечитывать!
Шестое правило: добавляйте ссылки на исходный код, который вы скопировали.
[...]
Если перейти по ссылке, то вы обнаружите, что:
Автора кода зовут Tomáš Procházka, он входит в топ-3% на Stack Overflow.
Но в данном случае вас это не спасло :)
Если код нуждается в комментариях, то следует его переписать
Комментарии не всегда пишутся к коду как таковому. Иногда нужно комментировать сами [бизнес]-процессы под которые пишется код.
В теории такое конечно должно быть не в комментариях, а в ТЗ/документации. Но в реальности часто логичнее это добавить и в виде комментария. Как минимум в виде какой-то сслыки на нужное место в этой самой документации.
Абсолютное безусловное высказывание скорее всего ложное, если это не формализм.
Если код нуждается в комментариях, то высока вероятность, что его стоит переписать
А теперь сравните с этим комментарием (слегка изменён, чтобы защитить виноватых):
// Magical formula taken from a stackoverflow post, reputedly related to
// human vision perception.
return (int) (0.3 * red + 0.59 * green + 0.11 * blue);
Любой, кто захочет разобраться в коде, вынужден будет искать эту формулу. А если бы вставили ссылку, то можно было бы гораздо быстрее найти источник.
А ещё лучше — ссылаться не на stackoverflow, а на более авторитетный источник: например — на W3C, и вообще это — массово используемая и широко известная формула.
Лучшие практики написания комментариев к коду