Школа
Веб-разработка

Поймал себя на мысли, что пишу слишком много комментариев к коду, но вроде это помогает в нём ориентироваться. Много комментариев в вашем коде? Когда их нужно писать?

Олег
8 фев 2024
👁 2133  
Веб-разработка

Поймал себя на мысли, что пишу слишком много комментариев к коду, но вроде это помогает в нём ориентироваться. Много комментариев в вашем коде? Когда их нужно писать?

Олег
8 фев 2024
👁 2133  
Игорь Петров
Разработчик, преподаватель Школы бюро
Полезно
 12
12
Непонятно
  
Войдите в Бюросферу, чтобы голосовать

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

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

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

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

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

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

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


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

// Для работы меню в ИЕ11// Костыль, пересчёт цены СДЭК без перезагрузки виджета// Избегаем коллизий с айди пользователей старого сайта// Для повышения оценки Гугль-аудита// Работает быстрее чем …, используем для оптимизации// Временно отключено из-за проблем с бэкендом

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

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

См. так же:

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

Веб‑разработка
Полезно
 12
12
Непонятно
  
Войдите в Бюросферу, чтобы голосовать
Отправить
Поделиться
Поделиться
Запинить
Твитнуть

Комментариев пока нет

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

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