Как можно обозначить комментарий

Комментарии

Как мы знаем из главы Структура кода, комментарии могут быть однострочными, начинающимися с // , и многострочными: /* . */ .

Обычно мы их используем, чтобы описать, как и почему работает код.

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

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

Новички склонны использовать комментарии, чтобы объяснять, «что делает код». Например, так:

// Этот код делает это (. ) и вот это (. ) // . и кто знает, что ещё. очень; сложный; код;

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

Про это есть хорошее правило: «Если код настолько запутанный, что требует комментариев, то, может быть, его стоит переделать?»

Рецепт: выносите код в функции

Иногда выгодно заменить часть кода функцией, например, в таком случае:

function showPrimes(n) < nextPrime: for (let i = 2; i < n; i++) < // проверяем, является ли i простым числом for (let j = 2; j < i; j++) < if (i % j == 0) continue nextPrime; >alert(i); > >

Лучший вариант – использовать отдельную функцию isPrime :

function showPrimes(n) < for (let i = 2; i < n; i++) < if (!isPrime(i)) continue; alert(i); >> function isPrime(n) < for (let i = 2; i < n; i++) < if (n % i == 0) return false; >return true; >

Теперь код легче понять. Функция сама становится комментарием. Такой код называется самодокументированным.

Рецепт: создавайте функции

И если мы имеем такой длинный кусок кода:

// здесь мы добавляем виски for(let i = 0; i < 10; i++) < let drop = getWhiskey(); smell(drop); add(drop, glass); >// здесь мы добавляем сок for(let t = 0; t < 3; t++) < let tomato = getTomato(); examine(tomato); let juice = press(tomato); add(juice, glass); >// . 

То будет лучше отрефакторить его с использованием функций:

addWhiskey(glass); addJuice(glass); function addWhiskey(container) < for(let i = 0; i < 10; i++) < let drop = getWhiskey(); //. >> function addJuice(container) < for(let t = 0; t < 3; t++) < let tomato = getTomato(); //. >>

Здесь комментарии тоже не нужны: функции сами говорят, что делают (если вы понимаете английский язык). И ещё, структура кода лучше, когда он разделён на части. Понятно, что делает каждая функция, что она принимает и что возвращает.

В реальности мы не можем полностью избежать «объясняющих» комментариев. Существуют сложные алгоритмы. И есть хитрые уловки для оптимизации. Но в целом мы должны стараться писать простой и самодокументированный код.

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

Итак, обычно «объясняющие» комментарии – это плохо. Но тогда какой комментарий считается хорошим?

Описывайте архитектуру Сделайте высокоуровневый обзор компонентов, того, как они взаимодействуют, каков поток управления в различных ситуациях… Если вкратце – обзор кода с высоты птичьего полёта. Существует специальный язык UML для создания диаграмм, разъясняющих архитектуру кода. Его определённо стоит изучить. Документируйте параметры и использование функций Есть специальный синтаксис JSDoc для документирования функций: использование, параметры, возвращаемое значение.

/** * Возвращает x, возведённое в n-ную степень. * * @param x Возводимое в степень число. * @param n Степень, должна быть натуральным числом. * @return x, возведённое в n-ную степень. */ function pow(x, n)

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

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

Также существуют инструменты, например, JSDoc 3, которые умеют генерировать HTML-документацию из комментариев. Получить больше информации о JSDoc вы можете здесь: https://jsdoc.app.

Почему задача решена именно таким способом?

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

Если есть несколько способов решить задачу, то почему вы выбрали именно этот? Особенно если ваш способ – не самый очевидный.

Без подобных комментариев возможна следующая ситуация:

1. Вы (или ваш коллега) открываете написанный некоторое время назад код и видите, что в нём есть, что улучшить.
2. Вы думаете: «Каким глупым я раньше был и насколько умнее стал сейчас», и переписываете его на «более правильный и оптимальный» вариант.
3. …Желание переписать код – это хорошо. Но в процессе вы понимаете, что «оптимальное» решение на самом деле не такое уж и оптимальное. Вы даже смутно припоминаете, почему, так как в прошлый раз вы уже его пробовали. Вы возвращаетесь к правильному варианту, потратив время зря.

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

В коде есть какие-то тонкости? Где они используются?

Если в коде есть какие-то тонкости и неочевидные вещи, его определённо нужно комментировать.

Итого

Комментарии – важный признак хорошего разработчика, причём как их наличие, так и отсутствие.

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

Комментируйте:

• Общую архитектуру, вид «с высоты птичьего полёта».
• Использование функций.
• Неочевидные решения, важные детали.

Избегайте комментариев:

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

Средства для генерации документации по коду, такие как JSDoc3, также используют комментарии: они их читают и генерируют HTML-документацию (или документацию в другом формате).

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

Разработчики используют этот комментарий, чтобы указать на необходимость будущего рефакторинга. Комментарий #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-менеджеров, как его улучшить и что добавить к рекомендательному письму.

HTML, как добавить комментарий

Чтобы добавить комментарий в HTML документ, используют специальный тег .

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

Или ты просто хочешь оставить себе напоминание, о том, что должно быть сделано.

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

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

HTML комментарий из одной строки

Простейший комментарий состоит из одной строки. Текст нужно разместить между последовательностью символов :

 h1>А это - заголовок. Он будет отображаться на странице.h1>

Обрати внимание, что восклицательный знак ставится только в начале, но не в конце тега.

HTML комментарий из нескольких строк

Если тебе нужно добавить длинный комментарий, который состоит из нескольких строк, это тоже можно сделать в HTML.

 Многострочный комментарий. В нем поместится очень много информации. Может даже целая книга. --> 

Если внутри комментария будут расположены какие-то HTML теги, то их на странице видно не будет.

 
Закомментированный заголовок
 
Этот абзац тоже не будет виден
 --> 

Ошибки

Ошибки в HTML комментариях чаще всего связаны с лишним пробелом или пропущенным восклицательным знаком:

 !-- Неправильный комментарий #1 --> -- Неправильный комментарий #2 --> 

Оба комментария написаны неправильно и будут отображаться на HTML странице.

Комментарии в коде (Visual Basic)

В примерах кодов часто встречается символ начала комментария ( ‘ ). Этот символ указывает компилятору Visual Basic игнорировать следующий текст или комментарий. Комментарии — это краткие заметки, внесенные в код, чтобы сделать чтение кода более легким.

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

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

' This is a comment beginning at the left edge of the screen. text1.Text = "Hi!" ' This is an inline comment. 

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

' This comment is too long to fit on a single line, so we break ' it into two lines. Some comments might need three or more lines. 

Правила комментирования

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

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

Также рекомендуется принять во внимание следующие моменты.

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

Вы можете добавить или удалить символы комментариев для блока кода, выбрав одну или несколько строк кода и выбрав кнопки Комментарий () и Раскомментировать () на панели инструментов Изменить .

Кроме того, можно добавить в код комментарии, поставив в начале текста ключевое слово REM . ‘ Однако символ и кнопкиРаскомментировать / комментарии проще в использовании и требуют меньше места и памяти.

См. также раздел

• Основные инстинкты— документирование кода с помощью xml-комментариев
• Практическое руководство. Создание XML-документации
• XML-теги для комментариев
• Соглашения о структуре программы и коде
• Оператор REM

Совместная работа с нами на GitHub

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