Хорошие комментарии к коду должны пояснять не ЧТО вы сделали, а ПОЧЕМУ. Это и еще 3 правила написания хороших комментариев.

Комментирование кода… Вы серьезно? Что за тема для обсуждения? На серверах скоро место закончится из-за таких статей.

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

Давайте перейдем к делу.

Хорошие комментарии — это не просто дополнение к коду. Это — его основа.

Вот несколько советов, которые помогут Вам написать более качественные комментарии…

#1 Ваши комментарии должны объяснять, ПОЧЕМУ, а не ЧТО вы сделали

«Комментарии не нужны. По хорошему коду и так должно быть понятно, что он делает».

Если вы тоже так считаете, то не понимаете, зачем вообще нужны комментарии.

Комментарии не должны объяснять, что делает код. Это должен делать сам код.

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

ПОЧЕМУ против ЧТО:

Код должен объяснять, ЧТО вы сделали.

Комментарии должны пояснять, ПОЧЕМУ использован этот код

или ПОЧЕМУ код что–то делает не очевидным на первый взгляд способом.

Плохой комментарий:

class Newsletter
 # removes stuff from newsletter
 def remove(stuff)
 …
 end
end

Хороший комментарий:

class Newsletter
 # Note(andreasklinger): In case we run into XYZ we need to remove the user to avoid
 # problems w/ ABC and DEFG's API. Read more here: https://.....
 def remove(stuff)
 …
 end
end

#2 Указывайте свое имя

В приложении Product Hunt мы всегда по привычке оставляли имя рядом с комментарием.

Например:

Note(andreasklinger): This is a comment.

Вы можете использовать для этого git blame.

Не забывайте, люди будут перемещать или редактировать ваш код. Когда-нибудь удаляли за другими лишние пробелы?

Конечно, никто не будет заниматься поисками автора при перемещении и редактировании кода.

Однако, при работе в небольших группах, имя в коде может принести определенную пользу. Это может помочь понять, почему появилась определенная часть кода, и кто должен эту часть переделать или исправить.

#3 Делайте все тщательно

«Следующий разработчик разберется».

Это утверждение — миф.

Обычно «следующему разработчику» некогда возиться с вашим кодом. Ему нужно заниматься своими делами, а ваш код просто отнимает у него драгоценное время.

Представьте, что человек, к которому попал на редактирование ваш код, вообще «не в теме» и ОЧЕНЬ ограничен во времени.

Пока Вы пишите код, все кажется понятным и очевидным. Но когда Вы закончите работу, те же вещи уже не будут очевидными ни для кого, включая вас самих.

Поясняйте, как работает ваша система. Не надейтесь, что это уже известно другим людям.
Поясняйте особенности внешних систем, которые вы используете
Поясняйте особенности внутренних систем, которые вы используете
Поясняйте, какие части системы относятся к предыдущей версии
Поясняйте (в случае с предыдущей версией) какую часть кода можно удалить. Напишите, например, «нужная часть заканчивается после строки X » или поставьте дату, если это возможно.
Поясняйте хаки, которые вам потребовалось сделать. Напишите, почему они работают.
Поясняйте внутренние взаимосвязи, которых нет в явном виде (например, другие системы, опирающиеся на структуру кода или API).
Будьте готовы писать длинные примечания, если это необходимо.
Никогда не используйте внешнюю документацию, если этого можно избежать. Если вся документация не будет в одном файле, люди не станут ее обновлять.
Попросите Ваших коллег также оставлять примечания к любому коду, где это уместно и необходимо.

#4 Избегайте лишних записей

Как правило, понятных частей кода больше, чем не непонятных.

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

Напишите комментарии.
После этого перечитайте их еще раз и посмотрите, что можно убрать или упростить

«Если Вы не можете объяснить это простыми словами, вы не до конца это понимаете».
Альберт Эйнштейн

Надеюсь, Вам помогут эти советы!

Комментарии – это не просто дополнение к хорошему коду. Это его основа.
Код делает сложные системы понятными для машин, а комментарии делают их понятными для людей.