Виды комментариев в программировании

Комментирование кода: хорошие, плохие и отвратительные комментарии

«Хороший код — это самодокументируемый код». Вы слышали эту фразу раньше? Я тоже. Более чем за 20 лет написания кода я слышал эту фразу чаще других. Это уже клише.

У этой фразы, как и у многих других клише, есть доля правды. Но смысл этого предложения давно потерялся, многие люди уже не понимают, что значит это выражение из-за постоянного и повсеместного использования.

В этой статье мы рассмотрим хорошие, плохие и отвратительные примеры комментирования в коде.

Начинающие разработчики должны помнить, что существует два типа комментариев в коде: поясняющие и документационные.

Документационные комментарии

Документационные комментарии предназначены для всех, кто когда-либо будет использовать ваш исходный код, но вряд ли сможет понять или прочитать его правильно. Если вы создаёте библиотеку или фреймворк, которые будут использоваться другими разработчиками, то вам нужно будет разработать документацию для API.

Чем больше API-документация отдалена от вашего кода, тем больше вероятность того, что она станет неточной или устаревшей с течением времени. Хорошим способом преодоления этой проблемы является документирование в самом коде. Таким образом вы сможете извлечь документацию с помощью специальных инструментов.

Посмотрите на пример кода из Lodash — популярной библиотеки для JavaScript:

 /** * Creates an object composed of keys generated from the results of running * each element of `collection` thru `iteratee`. The corresponding value of * each key is the number of times the key was returned by `iteratee`. The * iteratee is invoked with one argument: (value). * * @static * @memberOf _ * @since 0.5.0 * @category Collection * @param collection The collection to iterate over. * @param [iteratee=_.identity] The iteratee to transform keys. * @returns Returns the composed aggregate object. * @example * * _.countBy([6.1, 4.2, 6.3], Math.floor); * // => < '4': 1, '6': 2 >* * // The `_.property` iteratee shorthand. * _.countBy(['one', 'two', 'three'], 'length'); * // => < '3': 2, '5': 1 >*/ var countBy = createAggregator(function(result, value, key) < if (hasOwnProperty.call(result, key)) < ++resultВиды комментариев в программировании; >else < baseAssignValue(result, key, 1); >>);

Если вы сравните эти комментарии с онлайн-документацией, то увидите, что они одинаковы. При написании документационных комментариев убедитесь, что они соответствуют общепринятому стандарту и что они отличаются от уточняющих и поясняющих комментариев в самом коде. Некоторые популярные инструменты и стандарты включают использование JSDoc для JavaScript, DocFx для .Net и JavaDoc для Java.

Недостатком этих комментариев можно назвать лишний шум в коде, который они создают. Этот шум создаёт сложности при чтении кода другими разработчиками, участвующих в его разработке и поддержании.
Однако в большинстве современных редакторов есть возможность скрыть комментарии, чтобы лучше сосредоточиться на редактировании кода.

Поясняющие комментарии

Поясняющие комментарии предназначаются для всех (включая вас в будущем), кто будет заниматься поддержкой, рефакторингом и расширением вашего кода.

Зачастую уточняющий комментарий к вашему коду является его отражением. По пояснению можно судить нагружен ваш код или нет. Следует пытаться удалять пояснения в коде, упрощая его, ведь «хороший код — самодокументированный код».

Приведу пример плохого, но забавного пояснения:

/* * Replaces with spaces * the braces in cases * where braces in places * cause stasis. **/ $str = str_replace(array("")," ",$str);

Вместо того, чтобы писать амфибрахий для украшения запутанного кода, автор мог бы с пользой потратить время и поработать над функцией, облегчив чтение и понимание кода.

Поймите меня правильно, бывают моменты, когда небольшая порция юмора помогает расслабиться, особенно когда вы просто утопаете в работе. Но не пишите забавный комментарий, чтобы приукрасить плохой код. Именно из-за таких шуток в будущем мало кто захочет исправлять код и заниматься его рефакторингом.

Вам действительно хочется приукрасить рифмой свой плохой код, чтобы кодеры ухмыльнулись и проигнорировали его, двигаясь дальше?

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

/* Устанавливает значение 32 для переменной age */ int age = 32;

Тем не менее, бывают случаи, когда поясняющие комментарии нужны, вне зависимости от того, как выглядит ваш код.

Обычно это происходит, когда вам нужно добавить контекст к неинтуитивному решению.
Вот хороший пример из фреймворка Lodash:

function addSetEntry(set, value) < /* Не возвращать `set.add`, потому что эта цепочка вызовов не сработает в IE 11. */ set.add(value); return set; >

Иногда бывают случаи, когда оказывается, что на первый взгляд наивное решение проблемы является наилучшим после долгих экспериментов и размышлений. В подобных моментах почти неизбежна ситуация, когда другой разработчик, подумав, что он умнее, чем вы, начнёт копаться в коде, но в итоге выяснит, что ваше решение всё это время оставалось лучшим.

А иногда тем самым «более умным» кодером можете оказаться вы сами. Поэтому в таких случаях лучше оставлять комментарии к коду, чтобы в будущем сэкономить своё и чужое время и нервы.

Комментарий снизу полностью отражает суть мысли выше:

/** Уважаемый разработчик: Как только ты прекратишь пытаться «оптимизировать» этот код и поймёшь, какую ошибку ты допустил взявшись за это дело, пожалуйста, увеличь номер на счётчике ниже для следующего разработчика: количество_часов_потрачено_впустую_здесь = 42 **/

Опять же, комментарий сверху содержит больше юмора, чем пользы. Вам СЛЕДУЕТ оставлять комментарии, предупреждающие других от поиска какого-либо «лучшего решения», если вы сами уже пытались это сделать, но ничего хорошего из этого не вышло. В комментарии следует указать, какое решение вы пытались найти и почему вы решили, что оно не подходит в данной ситуации или не работает.

/* не используйте глобальную функцию isFinite(), потому что она возвращает true для нулевых значений */ Number.isFinite(value)

Отвратительные комментарии

Мы уже узнали, что такое хорошие и плохие комментарии к коду. Теперь пришло время ознакомиться с отвратительными комментариями.

К сожалению, в любой работе бывают моменты разочарования. Такое может случиться и во время написания кода, когда у вас возникнет соблазн выразить всё своё разочарование в комментариях.

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

/* Этот код — дно, я знаю. Можешь изучать его дальше и назвать меня тупицей. */

/* Класс, использующийся для обходного решения — Richard being a f***ing idiot */

Подобные моменты могут показаться забавными или, возможно, помогут вам разрядиться немного во время описания своего жизненного разочарования в комментарии. Но следует помнить, что иногда ваш код может дойти до продакшена. В таком случае вы не будете выглядеть умным или компетентным в своей сфере.

Уважайте себя и других разработчиков и не допускайте подобных комментариев в своём коде.

Источник

Пример добавления комментариев на 15 языках программирования

Давайте узнаем, что такое комментарии и почему они важны в программировании.

Мы также рассмотрим два распространенных типа комментариев и способы их написания на 15 различных языках программирования.

Что такое комментарии в программировании?

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

Говоря более формально, комментарий — это описание программы о том, как она работает, в простом читаемом формате. Обычно они используются в тех местах, где разработчику, читающему код, необходимо внести дополнительную ясность. Таким образом, это помогает улучшить читаемость кода и сократить время и общение, которые потребуются для передачи знаний.

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

Распространенные типы комментариев

Большинство языков программирования поддерживают 2 типа комментариев.

Как следует из названия, однострочные комментарии полезны, когда нужно добавить небольшой однострочный текст, например. особое состояние, постоянное значение, которое нуждается в небольшом описании. В то время как многострочные работают лучше, когда у нас есть больше информации, которую нужно добавить, например, описание функции и того, как ее можно использовать, и т. д.

Существуют и другие типы комментариев, такие как комментарии к документам, но они выходят за рамки этой статьи.

Зачем добавлять комментарии?

«Любой дурак может написать код, понятный компьютеру. Хорошие программисты пишут код, понятный людям». — Мартин Фаулер

Основным преимуществом добавления комментариев является улучшенная читабельность и лучшее понимание программы. Помимо этого, некоторые другие преимущества включают в себя —

• Комментарии позволяют вашим коллегам и даже другим разработчикам очень легко понять логику, не читая длинную документацию.
• Уменьшено общение между разработчиками для небольших сомнений
• Комментарии игнорируются компилятором/интерпретатором.
• Для программного обеспечения с открытым исходным кодом это обязательно, поскольку вам не придется объяснять каждую функцию миллионам разработчиков, которые хотят использовать эту конкретную программу.

Комментарии на нескольких языках

Отлично, теперь мы узнали о комментариях и о том, почему они полезны. Давайте рассмотрим, как мы можем добавлять комментарии на разных языках программирования.

// This is a single line comment in C/C++

/* This is slightly long multi line comment in C/C++ */

# This is a single line comment in Python

# This is slightly long # multi line comment in Python

// This is a single line comment in Java

/* This is slightly long multi line comment in Java */

# This is a single line comment in Ruby

=begin This is slightly long multi line comment in Ruby =end

// This is a single line comment in Golang

/* This is slightly long multi line comment in Golang */

– – This is a single line comment in Haskell

// This is a single line comment in Rust

/* This is slightly long multi line comment in Rust */

/* This is a single line comment in CSS */

/* This is slightly long multi line comment in CSS */

// This is a single line comment in Javascript

/* This is slightly long multi line comment in Javascript */

# This is a single line comment in R programming language

R не поддерживает многострочные комментарии.

% This is a single line comment in Erlang

R не поддерживает многострочные комментарии.

// This is a single line comment in PHP

/* This is slightly long multi line comment in PHP */

# This is a single line comment in Perl

=begin This is slightly long multi line comment in Perl =end

// This is a single line comment in Kotlin

/* This is slightly long multi line comment in Kotlin */

Вывод

В учебнике были рассмотрены основы комментариев и два распространенных типа — однострочные и многострочные. Я также попытался объяснить, почему комментарии полезны и их нужно писать по мере необходимости. Надеюсь, вы узнали что-то новое!

Продолжайте исследовать. Продолжай учиться! 👨‍💻

Источник