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

Просто чтобы уточнить: я не говорю вам никогда писать комментарии и опускать всех, кто это делает. Как и в любом правиле, есть исключения. Но я собираюсь возразить, что в большинстве случаев комментирование - не самое мудрое решение. Кроме того, это мое субъективное мнение, и я хотел бы услышать в ответах некоторую объективную критику!

Когда комментарии не работают: читаемость

Одна из наиболее очевидных причин для комментирования - объяснить, что делает определенный блок кода. Как ни парадоксально, это наименее очевидная причина не использовать комментарии.

Во-первых, если вашему коду нужны комментарии, чтобы придать смысл, вам следует сделать шаг назад и пересмотреть его. Что вы можете сделать, чтобы сделать его более читабельным? Есть ли что-нибудь, что можно было бы реорганизовать? Сам код является языком (тоже детерминированным), так зачем вам вводить другой язык (неоднозначный), чтобы он был понятным? Рассмотрим эти примеры: первый - плохой код с комментариями, второй - отредактированный и без комментариев. Какой из них легче читать?

Этот код является частью (воображаемой) системы рекомендаций, которая дает вам связанные страницы на основе тегов. Изучите различия между этими двумя: в первом файле был плохой, но тщательно документированный код, во втором - чистый и понятный код, но без комментариев. Мало того, что в нем нет комментариев, я осмелюсь вам попробовать написать их: просто нечего сказать, что еще не было сказано в самом коде. В этих примерах также есть подсказка для моего следующего аргумента. Вы можете это заметить?

Когда комментарии не работают: источник правды

Один из главных принципов, которым дорожит хороший программист, - СУХОЙ: не повторяйся. Он подчеркивает, что ваш код должен иметь единый источник правды. Используя это простое руководство, вы избежите ошибок и ошибок. Но комментарии прямо нарушают этот принцип.

Код никогда не лжет, иногда лгут комментарии (Рон Джеффрис)

Вы нашли проблему, о которой я упоминал в предыдущем примере? В комментарии к функции сказано, что у связанных страниц должно быть 75% совпадающих тегов, но сам код использовал 85%. Скорее всего, спецификация изменилась, программист обновил код, но забыл обновить комментарий. Теперь возникает двусмысленность, которая сбивает с толку всех, кто собирается работать с этим кодом.

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

Когда работают комментарии: документация по API

Хватит критики комментариев, теперь я расскажу о случаях, когда комментирование вполне уместно и даже желательно. Если вы разрабатываете API или библиотеку, предназначенную для конечного пользователя (или даже других программистов в вашей команде), вам понадобится документация. Документация также нарушает принцип единого источника истины, но это просто то, с чем мы должны иметь дело. Но что мы можем сделать, так это переместить документацию как можно ближе к коду. Существует множество решений (JavaDoc для Java, react-docgen для JS / React и т. Д.), Которые автоматизируют создание документации на основе комментариев. Изучите этот фрагмент из библиотеки material-ui: эти комментарии используются для создания документации по уценке, которая позже используется для создания веб-сайта документации:

Вы можете продвигать его еще дальше и создавать комментарии на основе других комментариев! Вот еще один пример из материала-ui, где комментарии / типы из определений TypeScript используются для генерации комментариев JavaScript:

Когда комментарии работают: принятие решений

Бывают случаи, когда код читабельный и лаконичный, но непонятно, почему он написан таким образом (может быть, нетрадиционным и / или неэффективным). Для этого могут быть очень веские причины, и в качестве объяснения и, возможно, предупреждения вы можете оставить комментарий, поясняющий это. Отличный пример того, что я имею в виду, - это комментарий:

// 
// Dear maintainer: 
// 
// Once you are done trying to 'optimize' this routine, 
// and have realized what a terrible mistake that was, 
// please increment the following counter as a warning 
// to the next guy: 
// 
// total_hours_wasted_here = 42 
//

Благодарим @jensroland и его ответ StackOverflow.

Когда работают комментарии: учебные пособия

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

const apples = 5; // set apples to 5

Просто не забудьте удалить их, когда переключаетесь с учебников на рабочую версию!

Спасибо, что дочитали до конца, надеюсь, вам понравилась эта статья, и вы будете более внимательны, оставляя комментарии в вашем коде. Я скажу, что эта статья вдохновлена ​​такими книгами, как Чистый код (не реклама / реферал), которые я настоятельно рекомендую вам прочитать.