Зачем комментировать исходный код и как это делать правильно

Мост между роботами и людьми

grunt-strip-json-commentsGulpjsonCommjsonComm.unComment()Какие задачи можно решать при комментировании JSON?

  • просто читать в JS или NodeJS формат jsonComm (с комментариями), удалять из них комментарии и далее верифицировать как обычный JSON в JSON.parse(); то же самое, что делает большинство проектов по добавлению комментариев в JSON. Работает быстро (десятки-сотни мкс).
  • читать не JSON, а файлы JS (с кодом) чтобы из оставшейся части взять некоторые константы как настройки (например, в NodeJS), когда файл JS будет их тоже использовать при своём исполнении в другом месте (на клиенте) — своеобразный шаблон с упрощением структуры конфигурации;
  • как в предыдущем пункте, но уже хочется изменить некоторые настройки после прочтения (например, в Ноде обновить номер сборки или внести настройки конфига), чтобы далее JS на клиенте, ничего не подозревая, использовал их. Это — аналог шаблона на чтение-запись.

ненужноjsonComm.unComment()jsonComm.change()Какие ещё задачи можно решать при комментировании JSON?


  • получить «валидный» доступ к комментариям jsonComm, переведя их сначала в пары «ключ#»-«комментарий», выбрав основу ключа из той строки, возле которой он найден, а затем, после парсинга из правильного JSON — обрабатывать их далее (например, переводя в другой формат);
  • работать с Yaml напрямую (но теряем признанную браузером/средой JS основу для валидации)
  • взаимное преобразование в Yaml и обратно через выше сделанный валидный JSON;
  • то же для XML; тогда получится кластер из четвёрки языков описания данных, 2 из которых признаны в браузерах и многочисленных вычислительных средах.

Комментарии в PHP

Комментарии в PHP могут быть однострочными и многострочными:

1) Однострочные комментарии в PHP создаются с помощью символов: //. Достаточно просто поставить этот символ перед строкой и она будет закомментирована.Такой вариант применятся в том случае, когда комментарий состоит только их одной строки.

2) Для реализации многострочных комментариев используются символы: /* и */. Такой вариант полезен, если комментарий занимает несколько строк.

Таким образом, мы научились делать

25.04.2017

Всем привет! Продолжаем изучать основы PHP с нуля! В этом уроке я расскажу, что такое комментарий в PHP и на практике попробуем прописать в коде свой комментарий. Но это еще не все. Еще хочу рассказать, как закомментировать код и для чего это вообще нужно делать.

Что такое комментарий в PHPКомментарий в PHP – это подсказка php-разработчика для быстрого ориентирования в коде, а также для правок.

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

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

Закомментировать код — это конвертировать одну или несколько строк кода в комментарии. Таким образом, вы можете (временно) исключить часть кода из компиляции.

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

Не закомментировано:

std::cout << 1;

1 std::cout<<1;

Закомментировано:

//    std::cout << 1;

1 //    std::cout << 1;

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

Не закомментировано:

std::cout << 1; std::cout << 2; std::cout << 3;

1 2 3

std::cout<<1;

std::cout<<2;

std::cout<<3;

Закомментировано символами однострочного комментария:

//    std::cout << 1; //    std::cout << 2; //    std::cout << 3;

1 2 3

//    std::cout << 1; //    std::cout << 2; //    std::cout << 3;

Закомментировано символами многострочного комментария:

/* std::cout << 1; std::cout << 2; std::cout << 3; */

1 2 3 4 5

/*      std::cout << 1;      std::cout << 2;      std::cout << 3; */

Есть несколько причин, почему следует использовать «закомментирование»:

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

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

   Причина №3: Поиск корня ошибки. Если вас не устраивают результаты работы программы (или вообще происходит сбой), полезно будет поочерёдно «отключать» части вашего кода, чтобы понять какие из них рабочие, а какие — создают проблемы. Если вы закомментируете одну или несколько строчек кода и программа начнёт корректно работать (или пропадут сбои), шансы того, что последнее, что вы закомментировали, является ошибкой — очень велики. После этого вы сможете разобраться с тем, почему же этот код не работает так, как нужно.

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

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

Комментируем код HTML

Аналогично комментируется и файл XML

Важно: всегда проверяйте предлагаемый в статьях код, хотя бы запросто — визуально) иначе могут быть ошибки. Обычная невнимательность при форматировании может стоить времени, например, показанный выше ЗАКОММЕНТИРОВАННЫЙ код частенько бывает ошибочен: заместо двух коротких дефисов вырисовывается длинное тире:

Обычная невнимательность при форматировании может стоить времени, например, показанный выше ЗАКОММЕНТИРОВАННЫЙ код частенько бывает ошибочен: заместо двух коротких дефисов вырисовывается длинное тире:

К сведению же:

как говорилось в предыдущей ремарке — так же и закомментный… код отображается в сгенерированном документе!

Имейте в виду это.

И вот ещё что:

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

Например:

будет виден в документе и функция замечательно отработает своё дело: т.е во фронтенде информации станет не видать, но вот в исходнике — она чётко отобразится! и это беспонтовый запрос к БД: всё это мелочь, но знать надобно!

Возможно поступить так, если выносить кусок кода из документа не хочется:


добавьте перед необходимым «лишним» кодом открывающий и … встроенная функция… и закрывающий …

Словом, вот так можно поступить, если код большой:

тогда исходник будет чистеньким!

Или попроще:

Закомментируем саму функцию в документе . Исходник в этих случаях относительно отработок функций будет чистеньким!

Нестандартный подход

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

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

При использовании тега скрипта или таблицы стилей, комментарии могут быть как однострочными, так и многострочными. Первые определяются конструкцией «//», которая с момента написания этих символов комментирует всю оставшуюся строку. Для того чтобы скрыть часть кода, следует воспользоваться синтаксическим описанием «/*» для открытия, и «*/» для закрытия комментария. В случае если после символов «/*» не будет прописана конструкция закрытия, то будет закомментирован весь оставшийся HTML-код.

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

Автоматическая генерация документации

Специальным образом оформленные комментарии (т. н. документирующие комментарии) используются для автоматического создания документации, в первую очередь, к библиотекам функций или классов. Для этого используются генераторы документации, например, такие как javadoc для языка Java, phpDocumentor для PHP, doxygen для C и C++ и др.

Документирующие комментарии как правило оформляются как многострочные комментарии в стиле языка Си. В каждом случае комментарий должен находиться перед документируемым элементом. Первым символом в комментарии (и вначале строк комментария) должен быть *. Блоки разделяются пустыми строками.

Пример документирующего комментария

/**
* Имя или краткое описание объекта
* 
* Развернутое описание
* 
* @имя_дескриптора значение
* @return тип_данных
*/

В некоторых средах программирования (например, Eclipse, NetBeans, Python, Visual Studio) документирующие комментарии используются в качестве интерактивной подсказки по интерфейсу классов и функций.

Когда нужны пояснения в коде, а когда — нет

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

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

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

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

После отладки их лучше удалить, оставив строки:

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

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

Пример на языке JavaScript:

Здесь и сам метод Number.isFinite (), и глобальная функция isFinite () проверяют, является ли параметр value конечным числом (то есть не ± ∞). Но если value = null, то isFinite (value) возвращает true, а Number.isFinite (value) возвращает false. Поэтому Number.isFinite (value) нельзя менять на isFinite (value).


Обязательно комментируйте код, если в нём есть какие-то тонкости и неочевидные вещи. Например:

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

Правильно будет так:

PHP Operators

Arithmetic operator: Addition (+) Arithmetic operator: Subtraction (-) Arithmetic operator: Multiplication (*) Arithmetic operator: Division (/) Arithmetic operator: Modulus (%) Assignment operator: x = y Assignment operator: x += y Assignment operator: x -= y Assignment operator: x *= y Assignment operator: x /= y Assignment operator: x %= y Comparison operator: Equal (==) Comparison operator: Identical (===) Comparison operator: Not equal (!=) Comparison operator: Not equal (<>) Comparison operator: Not identical (!==) Comparison operator: Greater than (>) Comparison operator: Less than (<) Comparison operator: Greater than or equal (>=) Comparison operator: Less than or equal (<=) Comparison operator: Spaceship (<=>) Increment operator: ++$x Increment operator: $x++ Decrement operator: —$x Decrement operator: $x— Logical operator: and Logical operator: or Logical operator: xor Logical operator: && (and) Logical operator: || (or) Logical operator: not String operator: Concatenation of $txt1 and $txt2 String operator: Appends $txt2 to $txt1 Array operator: Union (+) Array operator: Equality (==) Array operator: Identity (===) Array operator: Inequality (!=) Array operator: Inequality (<>) Array operator: Non-identity (!==) Conditional assignment operator: Ternary (?:) Conditional assignment: Null coalescing (??)

Документация XML

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

В таких комментариях можно размещать XML-дескрипторы, содержащие документацию по типам и членам типов, используемым в коде.

XML-дескрипторы, распознаваемые компилятором, перечислены в следующей таблице:

XML-дескрипторы для комментариев
Дескриптор Описание
<c> Помечает текст в строке как код
<code> Помечает множество строк как код
<example> Помечает пример кода
<exception> Документирует класс исключения (синтаксис проверяется компилятором)
<include> Включает комментарии из другого файла документации (синтаксис проверяется компилятором)
<list> Вставляет список в документацию
<param> Помечает параметр метода (синтаксис проверяется компилятором)
<paramref> Указывает, что слово является параметром метода (синтаксис проверяется компилятором)
<permission> Документирует доступ к члену (синтаксис проверяется компилятором)
<remarks> Добавляет описание члена
<returns> Документирует возвращаемое методом значение
<see> Представляет перекрестную ссылку на другой параметр (синтаксис проверяется компилятором)
<seealso> Представляет раздел «see also» («смотреть также») в описании (синтаксис проверяется компилятором)
<summary> Представляет краткий итог о типе или члене
<value> Описывает свойство

Чтобы увидеть, как это работает, рассмотрим пример кода, в который добавим некоторые XML-комментарии:

Компилятор C# может извлекать XML-элементы из специальных комментариев и использовать их для генерации файлов XML. Чтобы заставить компилятор сгенерировать XML-документацию для сборки, указывается опция /doc вместе с именем файла, который должен быть создан:

     csc /t:library /doc:MyApplication.xml MyApplication.cs

Данная команда сгенерирует файл XML по имени MyApplication.xml со следующим содержимым:

Обратите внимание на то, что компилятор на самом деле выполнил некоторую работу за вас: он создал элемент и также добавил элементы для каждого члена класса в этом файле. Каждый элемент имеет атрибут name с полным именем члена, снабженным префиксом — буквой, который указывает на то, является он типом (Т:), полем (F:) или членом (М:)

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

В языке HTML закомментировать часть кода проще всего с помощью специальных пар символов. Перед началом комментария необходимо указать «<!—«, а завершить его такими знаками: «—>». Таким образом, всё, что окажется внутри этой конструкции, будет скрыто для пользователя при загрузке страницы.

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

Ниже представлен пример правильно написания:

PHP комментарий коде

Существует 2 вида комментариев для кода PHP:

→ однострочный → многострочный ⇒ Однострочный комментарий для PHPДля однострочного комментария следует применять символы «// » или «# »

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

<?php // Однострочный комментарий для PHP # Однострочный комментарий для PHP (можно и так) echo «Привет читателям блога — сайт!!!»; // Мое приветствие (это комментарий) echo «Подпишись на обновление»; # подписка (это комментарий) ?>

⇒ Многострочный комментарий для PHP Многострочный комментарий для PHP начинается с символа «/* » и заканчивается символом «*/ ». Все, что находится между этими символами, будет игнорироваться и считаться как комментарий. Многострочный комментарий используется, если в записи несколько строк.

<?php /* Многострочный комментарий для PHP. Многострочный комментарий используется, если в записи несколько строк.!!!»; ?>

На экране вы только увидите вот такой текст:

P.S.: Всегда комментируйте свой код. Если вы считаете, что вспомните все, что делали в коде через 1-2 года, вы ошибаетесь, шанс очень маленький. Даже если и вспомните, то придется потратить кучу времени на изучение – что, куда и зачем… Сделайте приятное для себя будущего – закомментируй код и ты сам себе потом скажешь «СПАСИБО!!!». Оставь комментарий в коде, это займет 1 минуту времени, но сэкономит тебе в будущем целый день.

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

В следующей таблице приведены общие рекомендации по тому, какие типы комментариев могут предшествовать разделу кода.The following table provides general guidelines for what types of comments can precede a section of code. Это предложения; Visual Basic не применяет правила для добавления комментариев.These are suggestions; Visual Basic does not enforce rules for adding comments. В комментарий по желанию автора кода может быть включена любая информация.Write what works best, both for you and for anyone else who reads your code.

Тип комментарияComment type Описание комментарияComment description
ЦельPurpose Описание действий, совершаемых процедурой (но не того, каким образом совершаются эти действия)Describes what the procedure does (not how it does it)
ДопущенияAssumptions Список всех внешних переменных, элементов управления, открытых файлов, к которым осуществляется доступ из процедуры Lists each external variable, control, open file, or other element accessed by the procedure
Произведенный эффектEffects Список внешних переменных, элементов управления или файлов, на которые влияет данная процедура (если это влияние не очевидно)Lists each affected external variable, control, or file, and the effect it has (only if it is not obvious)
Входные данныеInputs Описание назначения аргументовSpecifies the purpose of the argument
Возвращаемое значениеReturns Описание значений, возвращаемых процедуройExplains the values returned by the procedure

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

Объявление каждой важной переменной должно предшествовать комментарию, описывающему ее назначение.Every important variable declaration should be preceded by a comment describing the use of the variable being declared.

Имена переменных, элементов управления и процедур должны быть функционально понятными, чтобы комментарии требовались только в случае особо сложных деталей реализации.Variables, controls, and procedures should be named clearly enough that commenting is needed only for complex implementation details.

Комментарии не могут располагаться за последовательностью продолжения строки в той же строке.Comments cannot follow a line-continuation sequence on the same line.

Можно добавить или удалить символы комментария для блока кода, выбрав одну или несколько строк кода и выбрав Комментарий ( ) и раскомментировать ( ) на панели инструментов изменить .You can add or remove comment symbols for a block of code by selecting one or more lines of code and choosing the Comment () and Uncomment () buttons on the Edit toolbar.

Примечание

Кроме того, можно добавить в код комментарии, поставив в начале текста ключевое слово .You can also add comments to your code by preceding the text with the keyword. Однако кнопки » символ» и » комментарий к комментарию» / Uncomment проще в использовании и занимают меньше пространства и памяти.However, the symbol and the Comment/Uncomment buttons are easier to use and require less space and memory.


С этим читают