Что писать в комментариях к коду?

Вопрос казалось бы достаточно простой, но сама по себе тема холиварная. Если капнуть глубже, то можно на просторах интернет найти много разных противоречивых ответов. Более того есть адепты разных движений, которые достаточно яростно будут отстаивать "свое самое правильное" решение.

Я бы рекомендовал рассматривать комментарии как инструмент позволяющий дополнять "историю" рассказываемую кодом т.е. комментарии не должны пересказывать код.

Возникает резонный вопрос, а что же стоит в них писать. В статье к этому посту предлагается достаточно интересный подход. Попробуйте в комментарии ответить на вопрос "Почему?", а код написать так, чтобы он отвечал на вопросы "Что?" и "Как?". Код описывает то как достичь результата и в нем невозможно описать зачем вы это делаете. Комментарий прекрасное место, для того чтобы дополнить код и ответить на вопрос Почему этот код написан т.е. какую проблему он должен решить.

UPD. Я подумал, что этот подход может технически хорошо вписаться\дополнить парадигму разработки через тестирование (test-driven development, TDD). По факту при TDD вы сначала в тестах (на уровне кода) описываете поведение своего кода и уже потом приступаете к реализации этого поведения. В этом пазле как раз не хватает начальной постановки т.е. ради чего все это делается. Технически можно начать с комментария к классу, в котором будет зафиксировано какую проблему должен решать класс без уточнения того как он этого добьется (ответ на вопрос "Почему?").

https://dzone.com/articles/why-should-i-comment-my-code