Как стать автором
Обновить

Лучшие практики написания комментариев к коду

Время на прочтение 7 мин
Количество просмотров 12K
Всего голосов 34: ↑31 и ↓3 +28
Комментарии 6

Комментарии 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, и вообще это — массово используемая и широко известная формула.
Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.