Комментарии в коде — это текст, который не участвует в работе программы, но виден в инструментах разработки. Обычно коменты выделяются символами // или /* */.

Из любого «тупого правила» есть исключения. Фишка в том, что они будут очевидны и вы сразу поймёте, когда правило неприменимо

Поделюсь своим «тупым правилом» по отношению к коментам в коде:

Из любого «тупого правила» есть исключения. Фишка в том, что они будут очевидны и вы сразу поймёте, когда правило неприменимо

Бесполезный комент отвечает на вопрос «что происходит?», полезный комент отвечает на вопрос «зачем мы это делаем?»

Если комент отвечает на вопрос «что происходит?» — это красный флаг, повод присмотреться к окружающему коду. Код сам должен отвечать на этот вопрос. Если по коду не понятно, что происходит — сделайте имена переменных и функций выразительнее, упростите код. Необходимость в коменте отпадёт, можно будет смело его удалить.

👎
// Добавляем товар в избранное function favorite(p) { … }
👌
function addToFavorite(product) { … }
// Показывается ли кнопка избранного
const favFlag = false 
const isFavBtnVisible = false


Другое дело — коменты, которые отвечают на вопрос «зачем мы это делаем?». Ответа на этот вопрос нет в коде, только на уровне задачи. И тут комент поможет лучше понять задачу, обратить внимание на неочевидные нюансы, сэкономить время.

// Для работы меню в ИЕ11
…

// Костыль, пересчёт цены СДЭК без перезагрузки виджета
…

// Избегаем коллизий с айди пользователей старого сайта
…

// Для повышения оценки Гугль-аудита
…

// Работает быстрее чем …, используем для оптимизации
…

// Временно отключено из-за проблем с бэкендом
…

На вопрос «зачем мы это делаем?» иногда так же можно ответить кодом, но обычно это ощутимо сложнее, чем оставить комент.

В следующем совете расскажу ещё о документирующих коментах и вредных коментах‑зарубках TODO и FIXME. А пока приглашаю уважаемых советчиков оставить в наших коментах свои коменты насчёт коментов!

См. так же:

P. S. Это был совет о веб‑разработке. Хотите знать всё о коде, тестах, фронтенд‑разработке, цеэсэсе, яваскрипте, рельсах и джейде? Присылайте вопросы.

Веб‑разработка
Отправить
Поделиться
Запинить

Рекомендуем другие советы