Заметки:
Мартин очень не любит комментарии, так что будет куча пунктов, почему комментарии — плохо.
Так почему комментарии — это неизбежное зло?
- Комментарии — всегда признак неудачи, потому что нам не удалось выразить свои мысли в коде так, чтобы всё было понятно без комментариев.
- Часто бывает, что между комментарием и кодом что-то вставляют и комментарий теряет смысл. А еще комментарии забывают обновлять и в будущем они могут ввести в заблуждение. Я, кстати, встречала ситуации, когда комментарий к какой-то переменной в итоге оказывался вдали от неё.
- Плохой код надо исправлять, а не комментировать. Аналогично с запутанным кодом. Согласна на 100%, хотя иногда это сложно и нет времени, чтобы написать нормально. Да, я знаю, что "нет времени" — это не аргумент.
- Обычно новая функция с хорошим названием сообщает то же самое, что и комментарий. Не используйте комментарий там, где можно использовать функцию или переменную.
- Самый хороший комментарий — тот, которого нет.
- Нельзя писать комментарий в спешке. На него требуется время, чтобы все продумать и описать.
- Избыточные. Особенно часто такое встречается в апи, когда комментируется каждая переменная и метод. Я сама встречала в библиотеках код в стиле:
/**
* День недели
*/
val dayOfTheWeek
Вот и смысл от комментария, который дублирует название и говорит что-то очевидное? То, что каждая функция и переменная должна иметь комментарий — чушь. Они загромождают код и вызывают путаницу. - Мартин пишет, что кто-то документирует все изменения в начала класса при редактировании. Впервые про такое слышу и согласна, что это жутко. Уже давно в в ide можно смотреть историю редактирования. Хотя тут есть небольшое исключение лично для меня: документирование для списка миграций у БД, чтобы было видно, в какой миграции что происходит, а не открывать каждую лично.
- Не пишите раздраженные комментарии. Даже если какой-то код вас злит. Другим разработчикам эта информация ни к чему.
- Заголовки с кучей черточек или звездочек. Они бессмысленно и мы все равно игнорируем их в коде.
- Иногда кто-то комментирует закрывающуюся скобку (while, if, else), чтобы было понятно, что именно закончилось. Лучше просто укоротите функцию.
- /* Добавлено Аня */ — не делайте так. ide и так помнят, кто внес изменение.
- Закомментированный код. Другие разработчики думают, что код важен и не удаляют его. Просто удалите код. Все равно потом можно будет найти его в истории, если внезапно понадобится.
- Комментарии html выглядят отвратительно. Не используйте их. Я никогда не использовала, так что ничего конкретного не могу сказать на тему, правда ли они так ужасны.
- Не пишите информацию про то, что будет где-то глубоко внутри и через несколько уровень абстракции.
- Слишком много информации в комментариях — тоже плохо. Особенно, если комментарий написан скучно или слишком заумно.
- Неочевидные и недостоверные комментарии, которые пробуждают больше вопросов, чем дают ответов.
Но есть и хорошие комментарии. Не ожидали? :)
- Юридические комментарии — это те, где сверху обычно пишут Copyright + ссылка на лицензию или документ. И то, там надо писать не весь текст лицензии, а оставлять именно ссылку.
- Комментарий к паттернам регулярных выражений. Тут согласна, потому что иногда сложно понять, что происходят. Хотя лучше паттерн переместить в специальный класс с хорошим названием.
- Объяснения к алгоритму или архитектуре. Иногда есть алгоритмы и логика, которые не поддаются названиям. Например: убери 10 символов из строки, добавь два других, убери 3 в центре и еще что-то. И всё это по бизнес-логике. Проще написать комментарий, почему убираем именно 10 и т.п.
- Пояснительные комментарии к аргументам из библиотеки или из кода, который нельзя изменить.
- Предупреждения. Например, что какой-то неочевидный пункт мега-важен или что какой-то тест будет слишком долго выполняться.
- // TODO: — необходимо что-то сделать, но сейчас невозможно. Регулярно их просматривайте. Я вот недавно обнаружила тудушку, которой почти год исполнился. :)
- Комментарии JavaDoc. Особенно для публичного апи, чтобы сторонние разработчики 100% всё поняли.
