Как писать комментарий к программе

Содержание

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

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

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

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

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

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

Специалист техподдержки 1С АО «Гринатом» , , можно удалённо , По итогам собеседования

Как писать комментарии в ютуб с телефона

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

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

Если вы сравните эти комментарии с онлайн-документацией, то увидите, что они одинаковы. При написании документационных комментариев убедитесь, что они соответствуют общепринятому стандарту и что они отличаются от уточняющих и поясняющих комментариев в самом коде. Некоторые популярные инструменты и стандарты включают использование 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 **/

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

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

Пять правил использования комментариев в коде

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

Правило 1. Пишите комментарии на высоком уровне абстракции

Рассмотрим такой пример кода на C++:

class Person < … >; class Registrator < public: … // Добавляет объект класса Person в вектор m_persons. // Возвращает false, если person уже занесен в m_persons, // иначе возвращает true. bool registerPerson( const Person … private: std::vector< Person >m_persons; … >;

Основная его проблема — нарушение инкапсуляции. Пользователю класса Registrator не интересно то, каким образом будет храниться информация. А если в будущем m_persons станет множеством std::set или просто поменяются имена переменных? В конечном итоге автор класса вообще перейдет на хранение записей в базе данных и комментарий в текущей формулировке потеряет всякий смысл.

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

Лучше было бы дать такое описание функции-члену registerPerson() :

// Осуществляет регистрацию сведений о личности. // Возвращает false, если регистрация окончилась неудачей, // иначе возвращает true. bool registerPerson( const Person

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

enum RegistrationResult < REG_OK, REG_FAILED >; RegistrationResult registerPerson( const Person

Правило 2. Не пишите избыточные комментарии

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

// Очищает страницу. void clearPage();

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

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

// Предусловие: // a >= 0 // // Постусловие: // | a — sqrt( a ) * sqrt( a ) |

Правило 3. Не устраняйте недостатки кода с помощью комментариев

Предположим, что перед нами код ужасного качества. Кто-то может попытаться выправить ситуацию с помощью комментариев. Тогда те, кто в будущем будут работать с этим кодом, вероятно, смогут с ним разобраться, но зачем тратить время таким образом? Рассмотрим пример плохого кода:

FigPtr fma( const std::vector< FigPtr > if( a.empty() ) < return nullptr; >FigPtr r = a[ 0 ]; int m = r->ar(); for( size_t i = 1; i < a.size(); ++i ) < int ar = a[ i ]->ar(); if( ar < m ) < m = ar; r = a[ i ]; >> return r; >

Догадаться о том, что делает этот код, не так уж сложно. Видно, что он находит какое-то минимальное значение. Но сказать точно, что это за значение, уже будет непросто. Можно было бы подробно задокументировать эту функцию, однако гораздо эффективнее дать понятные имена переменным и функциям:

FigurePointer findMinimumAreaFigure( const std::vector< FigurePointer > if( figures.empty() ) < return nullptr; >FigurePointer minAreaFigure = figures[ 0 ]; int minArea = minAreaFigure->getArea(); for( size_t i = 1; i < figures.size(); ++i ) < int area = figures[ i ]->getArea(); if( area < minArea ) < minArea = area; minAreaFigure = figures[ i ]; >> return minAreaFigure; >

Правила и рекомендации по комментированию в коде

Всем привет! Меня зовут Кристина Пешне, и я работаю младшим разработчиком веб-приложений в компании «ДоксВижн». Сегодня хочу представить статью о правилах комментирования в коде. Я не хочу сказать, что рекомендации, представленные в данной статье, являются аксиомами.

Нет, всегда найдутся две стороны: на одной стороне будут те, кто согласен с представленными рекомендациями, на другой — те, кто не согласен. Разнообразие мнений — это нормально и прекрасно.

Моё мнение, отражённое в данной статье, основывается на книге «Чистый код» Роберта Мартина.

Неужели хороший код не нуждается в комментариях?

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

Я приведу несколько примеров хороших и плохих комментариев.

Хорошие комментарии

Если эти комментарии присутствуют в вашем коде — это хорошо.

Юридические комментарии

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

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

Информативные комментарии

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

// Поиск по формату: kk:mm:ss EEE. MMM dd. yyyy сonst timeMatcher = new RegExp(‘\d*:\d*:\d* \w*. \w* \d*. \d*’);

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

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

Прояснение, представление намерений, пояснения к поведению

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

Как бы разработчик ни старался, такой код не сможет ответить на вопрос «почему здесь сделано именно так». Такие комментарии позволят облегчить работу тех, кто будет заниматься поддержкой, рефакторингом или расширением кода в дальнейшем. Разработчики обязательно скажут вам спасибо!

Также такие комментарии часто помогают объяснить магические числа в коде.

// Для дополнительных задач требуется добавлять префикс перед идентификатором, чтобы он не совпадал с каким-либо из id выездов orderStateDTO.setOrderId(«f_» + additionalTask.getId());

Комментарии TODO

Содержат пометки на будущее, информацию о том, что важно сделать, но не сейчас. Например, когда в будущем нужно сделать какой-то рефакторинг или сделать что-то, когда будет реализована зависимая часть кода. Большинство IDE позволяют вывести эти комментарии TODO в отдельное окно, что очень удобно.

После реализации основной логики какой-то задачи можно вернуться к таким комментариям и реализовать то, что ещё не было сделано, но необходимо. То есть получаем чек-лист на будущую работу, чтобы не искать потом по всему коду то, что вы забыли дописать. Это классический вариант технического долга. Можно больше не записывать себе задачки на листочке, а писать их прямо в коде!

// TODO: Удалить после удаления класса GroupTaskPanel // TODO: Проверить логику с приходящим значением null

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

Комментарии Jsdoc в общедоступных API (Это актуально также для аналогичных инструментов документирования в других языках)

Если код хорошо документирован в общедоступном API, с ним приятно и легко работать. В таком случае рекомендуется писать комментарии, которые будут упрощать формирование документации. Это документация метода или класса, которая показывается, когда вы генерируете документацию из вашего кода или когда вы наводите мышкой на название метода, и там показывается его Jsdoc (необходимые параметры, их типы, возвращаемое значение).

Jsdoc стоит использовать только с public методами и никогда с private методами. Private методы могут меняться без предупреждения, и в общедоступной документации они не описываются.

Усиление

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

// Вызов trim() важен. Он удаляет начальные пробелы, чтобы строка успешно интерпретировалась как список let listItemContent = match.group(3).trim();

Предупреждение о последствиях

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

// Don’t lower more than 500ms, otherwise there will be animation-problems with the Safari toolbar setInterval(function() < $(window).scrollTop(-1); resize(); >, 500);

Плохие комментарии

Бормотание или непонятные комментарии, шум

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

Избыточные комментарии

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

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

// вспомогательный метод: возвращает деление двух чисел, когда второе не равно 0 function numbersDivision(a,b) < // Если знаменатель равен 0, то возвращается null if(b==0) < return null; >// результат метода return a/b; >

Журнальные комментарии, ссылки на авторов

Нередко разработчики указывают, в рамках какой задачи были исправлены те или иные строки.

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

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

// Добавлено Иваном // Изменено в рамках задачи Task-675 // Поправлено 05.10.2019

Закомментированный код

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

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

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

Позиционные маркеры

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

/////////////////////////////////////////////////////////////////// ********************** комментарий **********************************

Комментарии за закрывающейся фигурной скобкой

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

В процессе рефакторинга эти скобки съезжают и обозначают уже конец другого блока, что может запутать разработчика. Любая современная IDE позволяет «схлопнуть» блок кода и увидеть, где его начало и конец. Если строчек действительно много — это хороший знак, что надо вынести часть кода в отдельный метод, чтобы повысить удобочитаемость.

try < while (что-то) < много строчек >// while много строчек > // try

Недостоверные комментарии

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

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

Обязательные комментарии

Некоторые компании заставляют разработчиков писать комментарии, считая, что код будет понятнее. Это неправильно. Это создаёт лишний мусор и не улучшает качество кода. Гораздо продуктивнее заставлять разработчиков правильно называть функции и классы, чем писать комментарии.

Заключение

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

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

Не комментируйте плохой код – перепишите его.

Код должен говорить сам за себя.

Код развивается, а комментарии – нет.

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

Каким бы хорошим ни был комментарий, он не оправдывает плохой код.

Комментарий должен отвечать не на вопрос «что делает код», а на вопрос «зачем».

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

IT-стандарты
Карьера в IT-индустрии
Лайфхаки для гиков

Источник: habr.com