Комментарии в коде - что и для кого в них пояснять? Jani Hartikainen приводит примеры хороших и плохих стилей комментирования.

Поводом к статье послужили рассуждения James Carr, в которых он критикует коментирование кода в том виде, в котором оно принято на сегодняшний день. А именно, бессмысленными являются такие примеры, как указание что должно быть выполнено в этом участке кода дополнительно, какие места должны быть в будущем отрефакторены, рассуждения на тему "а может быть здесь стоило сделать по другому" и т.п. Лучшая практика, по его мнению - найти ответственного за код человека и записать ему примечания в виде задачи (например в бэклог) или обсудить спорные моменты с коллегами, а не выносить их в комментарии, где всё равно никто их не увидит и не пофиксит.
В свою очередь, Jani Hartikainen говорит, что не все комментарии одинаково бесполезны. Как плохие примеры комментариев:

• - Один уровень абстракции комментария и когда. Так называемое "очевидное" комментирование, когда пояснения фактически дублируют легко читаемый код.
• - Комментарии TODO и рассуждения. Всё что записано в комментарии - фактически упущено из вида, так как очень редко программист возвращается к ранее написанному рабочему коду.

Хорошая практика:

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