​Bad Comments

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

Ясный и выразительный код с минимумом комментариев гораздо лучше громоздкого, сложного кода с большим количеством комментариев. Не тратьте время на написание комментариев, объясняющих созданную вами путаницу, - лучше потратьте его на исправление.

#comments #bad

​Avoid positional markers

Избегайте позиционных маркеров. Они обычно просто добавляют шум. Позвольте функциям и именам переменных вместе с правильными отступами и форматированием придать визуальную структуру вашему коду.

#comments

​TODO Comments

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

#comments

​Outdated comment

Устаревший комментарий. Комментарий, содержимое которого потеряло актуальность, считается устаревшим. Комментарии стареют довольно быстро. Обнаружив устаревший комментарий, обновите его или избавьтесь от него как можно скорее. Устаревшие комментарии часто «отрываються» от кода, который они когда-то описывали. Так в вашем коде появляются плавучие островки недостоверности и бесполезности.

#comments

​Don't have journal comments

Помните, используйте систему контроля версий! Нет необходимости в мертвом коде, комментируемом коде и особенно в журнальных комментариях. Используйте git log, чтобы получить историю!

#comments

​Only comment things that have business logic complexity.

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

#cleancode #comments

​Bad Comments

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

Ясный и выразительный код с минимумом комментариев гораздо лучше громоздкого, сложного кода с большим количеством комментариев. Не тратьте время на написание комментариев, объясняющих созданную вами путаницу, - лучше потратьте его на исправление.

#comments #bad

​Avoid positional markers

Избегайте позиционных маркеров. Они обычно просто добавляют шум. Позвольте функциям и именам переменных вместе с правильными отступами и форматированием придать визуальную структуру вашему коду.

#comments

​Commented Code

Приходилось ли вам работать с кодом, который содержит закомментированный код? Привычка оставлять такого рода комментарии является признаком плохого тона, и вот почему:

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

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

#comments

Functions instead of comments

Не используйте комментарии там, где можно использовать функцию или переменную. Постарайтесь переработать свой код так, чтобы их можно было удалить.

И запомните: хороший код не требует комментариев.

#comments #functions