Комментарии в коде — это текст, который не участвует в работе программы, но виден в инструментах разработки. Обычно коменты выделяются символами // или /* */.
Из любого «тупого правила» есть исключения. Фишка в том, что они будут очевидны и вы сразу поймёте, когда правило неприменимо
Поделюсь своим «тупым правилом» по отношению к коментам в коде:
Из любого «тупого правила» есть исключения. Фишка в том, что они будут очевидны и вы сразу поймёте, когда правило неприменимо
Бесполезный комент отвечает на вопрос «что происходит?», полезный комент отвечает на вопрос «зачем мы это делаем?»
Если комент отвечает на вопрос «что происходит?» — это красный флаг, повод присмотреться к окружающему коду. Код сам должен отвечать на этот вопрос. Если по коду не понятно, что происходит — сделайте имена переменных и функций выразительнее, упростите код. Необходимость в коменте отпадёт, можно будет смело его удалить.
👎// Добавляем товар в избранное function favorite(p) { … }
👌function addToFavorite(product) { … }
// Показывается ли кнопка избранного
const favFlag = false const isFavBtnVisible = false
Другое дело — коменты, которые отвечают на вопрос «зачем мы это делаем?». Ответа на этот вопрос нет в коде, только на уровне задачи. И тут комент поможет лучше понять задачу, обратить внимание на неочевидные нюансы, сэкономить время.
// Для работы меню в ИЕ11
…
// Костыль, пересчёт цены СДЭК без перезагрузки виджета
…
// Избегаем коллизий с айди пользователей старого сайта
…
// Для повышения оценки Гугль-аудита
…
// Работает быстрее чем …, используем для оптимизации
…
// Временно отключено из-за проблем с бэкендом
…
На вопрос «зачем мы это делаем?» иногда так же можно ответить кодом, но обычно это ощутимо сложнее, чем оставить комент.
В следующем совете расскажу ещё о документирующих коментах и вредных коментах‑зарубках TODO и FIXME. А пока приглашаю уважаемых советчиков оставить в наших коментах свои коменты насчёт коментов!
См. так же:
P. S. Это был совет о веб‑разработке. Хотите знать всё о коде, тестах, фронтенд‑разработке, цеэсэсе, яваскрипте, рельсах и джейде? Присылайте вопросы.