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

Второе правило: хорошие комментарии не оправдывают непонятный код

Ещё один способ некорректного использования комментариев — предоставление информации, которая должна содержаться в коде. Например, когда кто-то назвал переменную одной буквой и добавил комментарий с объяснением:

private static Node getBestChildNode(Node node) < Node n; // best child node candidate for (Node node: node.getChildren()) < // update n if the current state is better if (n == null || utility(node) >utility(n)) < n = node; >> return n; > 

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

private static Node getBestChildNode(Node node) < Node bestNode; for (Node currentNode: node.getChildren()) < if (bestNode == null || utility(currentNode) >utility(bestNode)) < bestNode = currentNode; >> return bestNode; > 

Как написали Керниган и Плогер в книге "The Elements of Programming Style": «Не комментируйте плохой код, а переписывайте его».

Третье правило: если не можете написать понятный комментарий, то проблема может быть в коде

Самый известный комментарий в исходном коде Unix звучит так: «Вряд ли вы это поймёте». Его вставили перед запутанным кодом переключения контекста. Дэннис Ричи позднее объяснил, что это был не наглый вызов, а высказывание в духе «На экзамене такого не будет». Но похоже, что он сам и его соавтор Кен Томпсон сами не поняли свой код, и позднее переписали его. Всё это напоминает о законе Кернигана:

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

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

Четвёртое правило: комментарии должны исключать путаницу, а не вносить её

Ни одно обсуждение плохих комментариев нельзя считать полным без этой истории из «Hackers: Heroes of the Computer Revolution» Стивена Леви:

[Питер Самсон] особенно усложнял ситуацию тем, что отказывался добавлять в свой исходный код комментарии с пояснением, что он делает в каждом конкретном случае. Одна из распространённых программ, написанных Самсоном, состояла из сотен инструкций на ассемблере с единственным комментарием после инструкции под номером 1750. Комментарий был такой: RIPJSB, и люди ломали головы над тем, что это означает, пока кто-то не догадался, что в 1750-м году умер Бах, и что Самсон написал аббревиатуру фразы “Rest In Peace Johann Sebastian Bach”.

Хотя я ценю хороший хак, но это не пример для подражания. Если ваш комментарий вносит путаницу, а не устраняет, то удалите его.

Пятое правило: объясняйте в комментариях не идиоматический код

Лучше комментировать код, который кто-нибудь может счесть ненужным или избыточным, вроде этого кода из App Inventor (источника всех моих положительных примеров):

final Object value = (new JSONTokener(jsonString)).nextValue(); // Note that JSONTokener.nextValue() may return // a value equals() to null. if (value == null || value.equals(null))

Без комментария кто-нибудь может «упростить» код или счесть его таинственным, но необходимым заклинанием. Сэкономьте время и нервы будущих читателей и напишите, для чего нужен этот код. Необходимо оценивать, нуждается ли код в объяснении. Когда я изучал Kotlin, я столкнулся в руководстве по Android с подобным кодом:

if (b == true) 

Я удивился, почему бы не заменить его просто на if (b) , как сделал бы это на Java. В результате небольшого исследования я выяснил, что допускающие пустое значение булевы переменные явным образом сравниваются с true, чтобы избежать уродливой проверки на null:

if (b != null && b) 

Я рекомендую не добавлять комментарии к распространённым идиомам, если только вы не пишете руководство для новичков.

Шестое правило: добавляйте ссылки на исходный код, который вы скопировали.

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

• какую задачу вы решали;
• кто предоставил код;
• почему это решение рекомендовано;
• что думали об этом комментаторы;
• работает ли это ещё;
• как его можно улучшить.

/** Converts a Drawable to Bitmap. via https://stackoverflow.com/a/46018816/2219998. */ 

Если перейти по ссылке, то вы обнаружите, что:

• Автора кода зовут Tomáš Procházka, он входит в топ-3% на Stack Overflow.
• Один из комментаторов предложил улучшение, уже внесённое в репозиторий.
• Другой комментатор предложил способ избежать пограничного случая.

// Magical formula taken from a stackoverflow post, reputedly related to // human vision perception. return (int) (0.3 * red + 0.59 * green + 0.11 * blue); 

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

Некоторые программисты могут не захотеть указывать, что они не сами написали код, но повторное использование кода может быть разумным шагом, экономящим время и дающим вам преимущество в виде большего количества проверяющих. Конечно, никогда не вставляйте код, который не понимаете. Люди копируют со StackOverflow много кода, который попадает под лицензирование Creative Commons, требующее указания авторства. Для этого достаточно указать ссылку на первоисточник.

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

// Many thanks to Chris Veness at http://www.movable-type.co.uk/scripts/latlong.html // for a great reference and examples. 

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

Конечно, не все ссылки ведут на Stack Overflow.

// http://tools.ietf.org/html/rfc4180 suggests that CSV lines // should be terminated by CRLF, hence the \r\n. csvStringBuilder.append("\r\n"); 

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

Восьмое правило: исправляя баги, добавляйте комментарии

Комментарии следует добавлять не только при первичном написании кода, но и при его изменении, особенно при исправлении багов. Взгляните:

 // NOTE: At least in Firefox 2, if the user drags outside of the browser window, // mouse-move (and even mouse-down) events will not be received until // the user drags back inside the window. A workaround for this issue // exists in the implementation for onMouseLeave(). @Override public void onMouseMove(Widget sender, int x, int y)

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

// Use the name as the title if the properties did not include one (issue #1425) 

Конечно, можно с помощью git blame найти коммит, в котором была добавлена или изменена строка. Однако пояснения к коммитам обычно краткие, и самые важные изменения (например, исправление бага №1425) могут не содержаться в последнем коммите (который, скажем, переместил метод из одного файла в другой).

Девятое правило: помечайте комментариями незаконченные реализации

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

// TODO(hal): We are making the decimal separator be a period, // regardless of the locale of the phone. We need to think about // how to allow comma as decimal separator, which will require // updating number parsing and other places that transform numbers // to strings, such as FormatAsDecimal 

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

Заключение

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

• лучшие практики
• комментирование кода
• никто не читает теги

• Блог компании VK
• Программирование
• Анализ и проектирование систем
• Проектирование и рефакторинг

Как правильно писать комментарии к коду: несколько важных примеров

Разработчики используют этот комментарий, чтобы указать на необходимость будущего рефакторинга. Комментарий #TODO позволяет обозначить, что именно нужно будет добавить в этой части кода и для чего это необходимо.

// TODO switch to the jest when it will works with modules import expect from 'expect'; import chalk from 'chalk'; 

solutionSlice:  // TODO move counter to server startTime: Date.now(), processState: isFinished ? solutionStates.shown : solutionStates.notAllowedToShown, waitingTime, >, 

# TODO Move to custom validator validates :first_name, length:  maximum: 40 >, format:  with: UsefulRegexp.without_spec_chars >, allow_blank: true 

Читайте также: Как читать чужой код: 6 правил, которые стоит помнить разработчику

#FIXME

Тег #FIXME показывает, что в этой части кода нужно что-то исправить. В некоторых случаях функциональность этого тега сливается с #TODO , поэтому #FIXME рекомендуется использовать, когда нужно указать на участок кода, от которого в будущем могут потенциально возникать проблемы.

# FIXME: Это нужно будет убрать, когда вернем аутентификацию для соцсетей user_from_session = get_session(conn, :current_user) 

// FIXME: это хак с путями, надо перерабатывать их root: path.join(process.env.HEXLET_IDE_APP_DIR, '..'), 

import/extensions: 0 # FIXME: remove when rule will be adjusted for new nodejs version 

#Warning

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

# Warning: The database defined as "test" will be erased and 

#Error

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

Как правильно применять теги

В каждой основной IDE есть плагины для работы с комментариями и их группировки. Например, в VS Code самый распространенный способ работы с такими комментариями — плагин Todo Tree , создающий дерево из групп комментариев для эффективной работы с ними.

В IDE от JetBrains комментарии #TODO и #FIXME автоматически определяются средой разработки в единые группы тегов. Подробнее об этом и том, как можно расширить функционал этой фичи на другие пользовательские комментарии, можно почитать на сайте JetBrains .

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

Комментарии к коду — зачем нужны и как писать

Комментирование кода — важная часть разработки. Узнайте, как правильно писать комментарии (с примерами), в блоге Kata Academy.

Комментарии в программном коде — неотъемлемая часть разработки, играющая важную роль в понимании, сопровождении и совершенствовании программ. В данной статье мы рассмотрим, почему комментарии важны, как их правильно писать и предоставим примеры оформления комментариев на примере языков программирования Java, Go и JavaScript.

Зачем нужны комментарии в коде

1) Понимания кода. Когда мы пишем комментарии в коде, мы создаем своего рода путеводитель для других разработчиков (и для себя в будущем). Эти комментарии помогают разобраться, что именно делает тот или иной кусок кода. Это особенно полезно в больших проектах или когда вы возвращаетесь к коду после некоторого времени. Другими словами, комментарии — это как пояснительные заметки, которые делают код более понятным. 2) Помощь в сопровождении. Комментарии также облегчают обслуживание кода. Когда вы вносите изменения, добавляете новые функции или исправляете ошибки, хорошо написанные комментарии служат своеобразным руководством. Они делают процесс изменения кода более плавным и быстрым, потому что вы можете лучше понять, как все взаимосвязано. Именно благодаря комментариям код становится более живым и понятным для разработчиков. 3) Документирование API. Если вы создаете библиотеки или API (набор готовых к использованию функций), хорошие комментарии становятся почти как пользовательская инструкция. Они помогают другим разработчикам правильно использовать ваш код, давая четкое представление о том, какие возможности предоставляет ваша библиотека или API. Представьте себе комментарии как описание к игре — чем лучше описание, тем проще новичку начать играть. Точно так же и с кодом. 4) Отладка и поиск ошибок. Комментарии могут быть невероятно полезными при отладке кода и поиске ошибок. Если вы или кто-то другой сталкиваетесь с проблемой, комментарии, поясняющие, почему было принято решение использовать тот или иной подход, могут существенно ускорить процесс поиска и устранения ошибок. 5) Сотрудничество в команде. Когда несколько разработчиков работают над одним проектом, хорошие комментарии становятся ключевым инструментом для коммуникации. Они помогают членам команды лучше понимать и согласовывать свои действия. Даже если вы работаете в одиночку, понятные комментарии могут сделать ваш код более доступным для сотрудников, которые могут присоединиться к проекту в будущем. 6) Соблюдение стандартов и лучших практик. Комментарии также являются отличным местом для указания на соблюдение стандартов кодирования и лучших практик. Если у вас в команде есть определенные требования к оформлению кода, комментарии — это место, где можно напомнить о них. Это помогает упростить процесс согласования стиля и поддерживает единообразие в коде. 7) Снижение зависимости от автора. Комментарии могут сделать код менее зависимым от конкретного разработчика. Если внимательно и четко описать, как и почему решались определенные задачи, другие разработчики смогут быстро вникнуть в суть и продолжить разработку, даже если оригинальный автор не доступен. 8) Оценка качества кода. Комментарии также могут служить индикатором качества кода. Хороший код сопровождается ясными и информативными комментариями, что может говорить о профессионализме и внимании к деталям разработчика. В целом, писать комментарии — не только хорошая практика, но и важный инструмент для улучшения понимания, поддержки и развития вашего кода.

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

1) Краткость и ясность. Комментарии должны быть краткими, но информативными. Избегайте излишних деталей и фраз, фокусируйтесь на ключевых аспектах кода. 2) Свежесть и актуальность. Комментарии должны отражать текущее состояние кода. Если код изменяется, обновляйте и комментарии, чтобы избежать путаницы. 3) Избегайте очевидного. Не пишите комментарии, которые очевидны из самого кода. Комментарии должны дополнять, а не повторять. 4) Использование правильного языка. Используйте грамотный язык и правила оформления текста. Четкий и профессиональный стиль дает дополнительную ясность.

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

1. Java

System.out.println("Hello, Java world!");

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

2. Go

package main

import ( "fmt" )

func main() < // Print “Hello, World!” to console fmt.Println("Hello, World!") >

3. JavaScript

/* Код ниже изменит

на веб-странице заголовок с 

и параграф с 

document.getElementById("myH").innerHTML ="Моя первая веб-страница";

document.getElementById("myP").innerHTML ="Мой первый параграф.";

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

Читать еще:

5 задач на логику от HR-менеджеров для разработчиков и других IT-специалистов Мы собрали пять популярных задач на логику и добавили в них свои детали, чтобы было интереснее решать. Такие упражнения можно использовать для подготовки к собеседованиям или для тренировки мышления.

Как понять, что пора менять работу — 5 признаков Как понять, что пришло время сменить работу, найти идеальное место для своего развития. Читайте подробнее в блоге Kata Academy.

Как начать карьеру программиста без опыта работы? Эта статья поможет понять, какие шаги необходимо предпринять, чтобы стать успешным программистом без опыта.

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

Вы наверняка это слышали: «Хороший код является самодокументированным».

Я больше 20 лет зарабатываю написанием кода, и слышал эту фразу чаще всего. Это клише.

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

Она истинна? Да.

Означает ли она, что вы никогда не должны комментировать код? Нет.

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

Для новичков: существует два разных вида комментариев. Я называю их документирующими комментариями и поясняющими комментариями.

Документирующие комментарии

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

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

Вот пример документирующего комментария из популярной JS-библиотеки Lodash:

 /** * 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[key]; >else < baseAssignValue(result, key, 1); >>);

Когда пишете документирующие комментарии, удостоверьтесь, что делаете это в соответствии с подходящим стандартом, и что комментарии можно легко отличить от любых инлайновых поясняющих комментариев, которые вы тоже можете добавлять. Некоторые популярные и хорошо поддерживаемые стандарты и инструменты: JSDoc для JavaScript, DocFx для .NET, JavaDoc для Java.

К недостаткам документирующих комментариев можно отнести то, что они способны сильно «зашумлять» код, а программистам, которые активно участвуют в сопровождении кода, труднее их читать. Но зато большинство редакторов поддерживают «сворачивание блоков кода» (code folding), что позволяет скрывать комментарии и уделять всё внимание только коду.

Сворачивание комментариев в коде Visual Studio.

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

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

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

Вот пример плохого — хотя и очень забавного — поясняющего комментария:

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

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

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

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

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

Например, не делайте так:

/* set the value of the age integer to 32 */ int age = 32;

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

function addSetEntry(set, value) < /* Don't return `set.add` because it's not chainable in IE 11. */ set.add(value); return set; >

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

Иногда таким программистом можете оказаться вы сами.

В таких ситуациях лучше сэкономить чужое время и написать комментарий.

Этот комментарий-заглушка прекрасно иллюстрирует описанное:

/** 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 **/

Конечно, это скорее развлечёт, чем поможет. Но вы ДОЛЖНЫ оставлять комментарии, предостерегающие других от поиска, казалось бы, очевидно «лучшего решения», если вы уже испробовали и отвергли другие варианты. При этом комментарий должен описывать, что вы пытались сделать и почему отказались от таких решений.

Простой пример в JavaScript:

/* don't use the global isFinite() because it returns true for null values */ Number.isFinite(value)

Злой

Итак, вы прочитали про хорошего и плохого, а что насчёт злого?

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

Если поработать с достаточным количеством кодовых баз, то вам встретятся комментарии от циничных и депрессивных до мрачных и злобных.

/* This code sucks, you know it and I know it. Move on and call me an idiot later. */

/* Class used to workaround Richard being a f***ing idiot */

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

Не делайте этого.

• комментирование кода
• никто не читает теги

• Блог компании VK
• Программирование
• Совершенный код
• Проектирование и рефакторинг
• IT-стандарты