Как писать хорошие комментарии к коду: «зачем», а не «как»

[AntonioXXX]

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

[ua9msn]

Мне не кажется что этот комментарий тянет на отличный. Из кода и так понятно что он делает. А решать архитектурные проблемы комментариями вообще плохая идея. Лучше продумать обязательность/необязательность key.
Разрешите пример хорошего комментария, на мой взгляд:

// not using Number.isFinite here because it must work in IE11 without polifill
if(!isFinite(arg)) return; 
...

Тут четко понятно почему сделано так а не иначе, как раз в духе «не что, а зачем»

[E_STRICT]

Есть большая вероятность, что этот коммент переживёт IE 11. Для таких штук лучше оставлять todo, чтобы можно было потом отслеживать их статус помощью IDE.

// @todo Replace with Number.isFinite once we drop support for IE11.
if(!isFinite(arg)) return; 

[avdosev]

А не лучший вариант сделать этот комментарий внутри функции isFinite (или как часть документации)? Не плодить же такой комментарий для каждого использования isFinite.

[E_STRICT]

Внутри не получится. Это встроенная JS функция.

Лучшим вариантом было бы использовать какой-нибудь линтер с настройками браузерной поддержки.

[Sano000]

с «зачем» тоже все не просто. Чем меньше квалификация и знаний о бизнес логике конкретного приложения, тем больше «зачем» возникает.

А с ними и комментарии по три строчки, хотя более опытному программисту все и так ясно с первого взгляда.

Так что нужна еще одна статья на предмет когда писать «зачем», а когда не писать.

[joyfolk]

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

[maxzhurkin]

IMHO, следовало затребовать полный перечень используемых сочетаний флагов и хотя бы обзор потенциально используемых, в форме, близкой к ультимативной

[maxzhurkin]

del