Привет, Хабр! Представляю вашему вниманию перевод статьи «Writing good comments: the why, not the how» автора Jack Franklin.



Комментирование кода в программистской среде нередко считается пустой тратой времени или неким сигналом о том, что код можно и улучшить. Вот цитата из файла CONTRIBUTING.md, который я нашёл на Гитхабе (и таких примеров очень, очень много):

Комментариев следует избегать. Если ваш код нельзя понять без комментариев, перепишите его так, чтобы он сам себя объяснял.

Я считаю, что в большинстве случаев такой совет будет неудачным и неверным.