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

Проблемы

Теперь, когда мы обсудили, как работает элемент <pre>, давайте рассмотрим несколько потенциальных проблем, которые могут возникнуть при его использовании.

Выход за пределы элемента

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

Ниже приведён пример макета страницы с выходящим за границы содержанием.

Давайте рассмотрим несколько вариантов решения данной проблемы.

Решение №1: Вывод полосы прокрутки

Одним из способов избежать описанной выше проблемы является отображение полосы прокрутки. Это действенно когда содержание элемента <pre> слишком широкое. Можем воспользоваться CSS:

pre {
    overflow: auto;
}

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

Решение №2: Перенос текста на новую строку

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

pre {
    white-space: pre-wrap;
}

Отображение HTML

Существует определённый тип исходного кода, с которым немного сложнее работать внутри элемента <pre>, я говорю о HTML. Ранее я уже упоминал о том, что вы можете вложить HTML элементы внутрь элемента <pre>. Но что, если мы захотим показать эти теги так, чтобы читатель смог их увидеть в отображаемом коде?

Для отображения HTML тегов в браузере вы, как правило, должны заменить HTML скобки. Допустим, мы захотели показать следующую разметку внутри тегов <pre>:

Заменяем символы <, >, и «:

<pre><code>&lt;nav class=&quot;main-navigation&quot;&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/&quot;&gt;Home&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;about.html&quot;&gt;About Us&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;contact.html&quot;&gt;Contact Us&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;/nav&gt;</code></pre>

К счастью, существует множество инструментов, которые помогут вам сделать это. К примеру, Free Online HTML Escape Tool.

Случайные пробелы

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

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

Если мой HTML документ имеет следующую структурную (отступы для иллюстрации вложенных элементов), то отображение будет следующим:

<html>
    <head>
        <title>My tutorial</title>
    </head>
    <body>
        <section>
            <article class="main-content">
                <h1>My Tutorial's Title</h1>
                <p>Here's some example JavaScript:</p>
                <!-- My pre element -->
                <pre><code>&lt;script type=&quot;text/javascript&quot;&gt;
    console.log('Hello there');
    &lt;/script&gt;</code></pre>
            </article>
        </section>
    </body>
</html>

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

<script type="text/javascript">
                        console.log('Hello there');
                    </script>

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

<html>
    <head>
        <title>My tutorial</title>
    </head>
    <body>
        <section>
            <article class="main-content">
                <h1>My Tutorial's Title</h1>
                <p>Here's some example JavaScript:</p>
                <!-- My pre element -->
                <pre><code></code></pre>
            </article>
        </section>
    </body>
</html>

Теперь содержание будет отображаться вот так:

<script type="text/javascript">
    console.log('Hello there');
</script>

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

Для PHP комментарии и правила их использования так же отличаются. Так если вам нужно закомментировать какую-то одну строку или сделать пометку в теле фрагмента кода, то вам нужно использовать двойной слэш (//). Например:

PHP

<?php
if (is_front_page() ) {
echo(‘<style>…</style>’); // действие для главной страницы
} else {
echo(‘<style>…</style>’); // действие для не главной страницы
}
?>

1
2
3
4
5
6
7

<?php

if(is_front_page()){

echo(‘<style>…</style>’);// действие для главной страницы

}else{

echo(‘<style>…</style>’);// действие для не главной страницы

}
?>

Если же вам нужно закомментировать несколько строк, то для этого можно использовать символы для комментирования /* и */, такие-же как для css-стилей, но с одним отличием:

PHP

<?php
/* if( is_page_template( ‘page-templates/contact.php’ ) ) {
$sidebar = ‘colornews_contact_page_sidebar’;
}
else {
$sidebar = ‘colornews_right_sidebar’;
} */
?>

1
2
3
4
5
6
7
8

<?php

/*  if( is_page_template( ‘page-templates/contact.php’ ) ) {

            $sidebar = ‘colornews_contact_page_sidebar’;
         }
         else {
            $sidebar = ‘colornews_right_sidebar’;
         } */

?>

Обратите внимание! Символы комментария нужно ставить внутри фрагмента PHP-кода. Если вы поставите /* перед <?php , а */ после ?>, то комментирование работать не будет.. Сегодня я вам показала все основные способы комментирования для HTML, CSS и PHP которые вы можете использовать при создании сайтов

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

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

А у меня на сегодня все. До встречи в следующих статьях!

С уважением Юлия Гусарь

Чем комментарии могут помочь программисту

Комментарии, в зависимости от ситуации, делают сразу несколько полезных вещей:

Помогают быстрее разобраться в коде — если появилась ошибка или нужно что-то изменить d программе

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

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

Как закомментировать HTML, PHP, CSS.

Для того, чтобы закомментировать HTML строчки кода, оберните их символами – «
».

Пример:

Закомментировать PHP, можно, используя символы – «/*
и */
».

Пример:

В случае с CSS, применяются те же символы, что и у PHP — «/*
и */
».

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

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

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

Пример:

/* #optin input {
background: #960e17;
border: 1px solid #111 } */

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

Возможно, что Вас ещё заинтересует:

Надеюсь, что Вам была полезна информация о том, как закомментировать HTML!

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

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

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

На сегодня это всё. До новых статей.

Тег

Если не использовать встраиваемые скрипты, то что тогда? Конечно, подключать все скрипты извне — не вариант, иногда иметь какой-то Javascript с данными внутри HTML-документа очень удобно: нет лишних HTTP-запросов, не нужно делать дополнительных роутов на стороне сервера.

Поэтому я предлагаю ввести новый тег — <safescript>, содержимое которого будет полностью подчинятся обычным правилам HTML — будут работать HTML entities для экранирования контента — и поэтому встраивание в него любого скрипта будет абсолютно безопасным.

При этом нет необходимости дожидаться реализации этого тега в браузерах. Я написал очень простой полифил safescript, который позволяет использовать его прямо сейчас. Вот всё, что для этого нужно:

Код внутри <safescript> выглядит ужасно и непривычно. Но это код, который попадет в сам HTML. В шаблонизаторе, который вы используете, можно сделать простой фильтр, который будет вставлять тег и экранировать все его содержимое. Вот так может выглядеть код в шаблонизаторе Django:

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

Старый ответ

Кто вы комментируете?

  • Разработчики? Затем прокомментируйте в PHP. Пример:

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

  • Пользователи? Затем прокомментируйте в HTML. Пример:

    Здесь намерение состоит в том, чтобы рассказать что-то полезное для пользователей, которые, например, сканируют ваш веб-сайт или делают что-то, что манипулирует HTML (единственный допустимый пример, который я видел бы, заключается в том, что выполнение реального API слишком дорого для вас, поэтому вы авторизуете и приглашаете пользователей непосредственно анализировать HTML-код).

Помните, что:

  • Комментарии HTML могут быть видны всем,

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

Отступ текста в HTML при помощи padding

Этот способ очень похож на предыдущий, но если margin задавал отступ до текста как бы снаружи тега, то padding будет задавать отступ внутри.

PHP

<div style=”paddint-top:20px;”> Текст блока </div>

1 <div style=”paddint-top20px;”>Текстблока<div>

Так же можно присвоить класс в HTML коде или воспользоваться уже существующим и дописать это свойство ему:

CSS:

PHP

.text-block {
padding: 20px 10px 15px 20px;
}

1
2
3

.text-block{

padding20px10px15px20px;

}

С его помощью так же можно задать разные отступы текста в HTML:

  • padding-left — слева
  • padding-right — справа
  • padding-top — сверху
  • padding-bottom — расстояние снизу
  • padding: 25px; — отступ со всех сторон.

Что такое комментарий?

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

Эти комментарии не для компьютера – они существуют, чтобы объяснить формат файла конфигурации любому, кто его читает. Знак # перед каждой строкой сообщает компьютеру, что это строка комментария – компьютер должен игнорировать ее, пропустить ее и попытаться интерпретировать следующую строку, которая не начинается с символа #.

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

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

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

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

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

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

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

→ однострочный
→ многострочный

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

Пример 3. Акциз диапазона

Акциз нескольких строк

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

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

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

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

⇒ Многострочный комментарий для PHP

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

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

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

Однострочный комментарий начинается с символа маршрута #. Они могут быть в начале строки, а также за выражением. Не столь известный вариант комментариев — комментарий блока. С его помощью можно выделить целые секции. «Магический комментарий» теперь определяет кодирование; в зависимости от программы файл сохраняется в другой кодировке.

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

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

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

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

Это стоит только времени или почему нужно прокомментировать? Это просто потому, что вы все еще можете узнать через год, почему вы запрограммировали то или это и почему вы ничего не сделали

Кроме того, часто важно, чтобы коллеги могли понять подпрограммы, чтобы они могли быстрее интегрироваться в код, если это необходимо

Как эксплуатируется уязвимость

Конечно, когда вы просто пишете какой-то код, трудно представить, что вы напишете в строке </script> и не заметите проблем. Как минимум, подсветка синтаксиса даст вам знать, что тег закрылся раньше времени, как максимум, написанный вами код не запустится и вы будете долго искать, что произошло. Но это не является основной проблемой с этой уязвимостью. Проблема возникает там, где вы вставляете какой-то контент в Javascript, когда генерируете HTML. Вот частый кусок кода приложений на реакте с серверным рендерингом:

В </script> может появиться в любом месте, где данные поступают от пользователя или из других систем. не будет менять такие строки при сериализации, потому что они полностью соответствуют формату JSON и Javascript, поэтому они просто попадут на страницу и позволят злоумышленнику выполнить произвольный Javascript в браузере пользователя.

Другой пример:

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

Но на закрывающем теге </script> приколы не заканчиваются. Опасность представляет и открывающий тег <script>, если перед ним в любом месте есть символы , которые в обычном HTML обозначают начало многострочного комментария. Причем в этом случае вам уже не поможет подсветка синтаксиса большинства редакторов.

Что видит здоровый человек и большинство подсветок синтаксиса в этом коде? Два тега <script>, между которыми находится параграф.

Что видит больной парсер HTML5? Он видит один (!) незакрытый (!) тег <script>, содержащий весь текст со второй строчки до последней.

Я до конца не понимаю, почему это так работает, мне понятно лишь, что встретив где-либо символы , парсер HTML начинает считать открывающие и закрывающие теги <script> и не считает скрипт законченным, пока не будут закрыты все открытые теги <script>. То есть в большинстве случаев этот скрипт будет идти до конца страницы (если только кто-то не смог внедрить еще один лишний закрывающий тег </script> ниже, хе-хе). Если вы до этого не сталкивались с подобным, то можете подумать, что я сейчас шучу. К сожалению, нет. Вот скриншот DOM-дерева примера выше:

Самое неприятное, что в отличие от закрывающего тега </script>, который в Javascript может встретиться только внутри строковых литералов, последовательности символов и могут встретиться и в самом коде! И будут иметь точно такой же эффект.

Как комментируют функции и библиотеки

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

Например, документирующий комментарий из заголовка библиотеки Lodash для JavaScript выглядит так:

Кроме этого, в заголовочных комментариях к функциям указывают стандартный набор сведений:

  • описание того, что и как делает функция/процедура;
  • условия, при которых она работает или не работает;
  • описание входные параметров, если есть;
  • описание возвращаемого значения.

Пример из той же библиотеки Lodash:

Главное здесь — избегать бессмысленных комментариев. Вот пример плохого описания процедуры на языке 1С:

Новый ответ

Вы легко справляетесь, так как в вашем коде нет ни строк PHP, ни комментариев. Это означает, что комментирование этого фрагмента кода так же просто, как:

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

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

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

Несколько замечаний:

  • Почему я использую NOWDOC вместо простой строки?

    Простая строка будет разбита на строку 5 (на «Says» hello «). Строка с одним кадром будет разбита на строку 2 (на» Вы»).

  • Почему я использую NOWDOC вместо HEREDOC?

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

  • Что это за страшный GUID2328…?

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

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

  • Это повлияет на производительность веб-приложения, верно?

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

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

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

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

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

Описывайте архитектуру

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

Документируйте параметры и использование функций

Есть специальный синтаксис JSDoc для документирования функций: использование, параметры, возвращаемое значение.
Например:

Подобные комментарии позволяют нам понимать назначение функции и правильно её использовать без необходимости заглядывать в код.
Кстати, многие редакторы, такие как WebStorm, прекрасно их распознают для того, чтобы выполнить автодополнение ввода и различные автоматические проверки кода.
Также существуют инструменты, например, JSDoc 3, которые умеют генерировать HTML-документацию из комментариев

Получить больше информации о JSDoc вы можете здесь: http://usejsdoc.org/.

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

Важно то, что написано. Но то, что не написано, может быть даже более важным, чтобы понимать происходящее

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

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

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

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

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

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

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

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: Тестирование нового кода. Вместо удаления старого кода, вы можете его закомментировать и оставить для справки, пока не будете уверены в том, что ваш новый код работает так, как нужно. Как только вы будете уверены в новом коде, то сможете без проблем удалить старые фрагменты кода. Если же новый код у вас будет работать не так, как нужно, то вы сможете его удалить и откатиться к старому коду.

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

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

Однострочные комментарии — это комментарии, которые пишутся после символов . Они пишутся в отдельных строках и всё, что находится после этих символов комментирования, — игнорируется компилятором, например:

std::cout << «Hello, world!» << std::endl; // всё, что находится справа от двойного слеша, — игнорируется компилятором

1 std::cout<<«Hello,world!»<<std::endl;// всё, что находится справа от двойного слеша, — игнорируется компилятором

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

std::cout << «Hello, world!» << std::endl; // cout и endl находятся в библиотеке iostream
std::cout << «It is so exciting!» << std::endl; // эти комментарии усложняют чтение кода
std::cout << «Yeah!» << std::endl; // особенно, когда строки разной длины

1
2
3

std::cout<<«Hello,world!»<<std::endl;// cout и endl находятся в библиотеке iostream

std::cout<<«It isso exciting!»<<std::endl;// эти комментарии усложняют чтение кода

std::cout<<«Yeah!»<<std::endl;// особенно, когда строки разной длины

Размещая комментарии справа от кода, мы затрудняем себе как чтение кода, так и чтение комментариев. Следовательно, однострочные комментарии лучше размещать над строками кода:

// cout и endl находятся в библиотеке iostream
std::cout << «Hello, world!» << std::endl;

// теперь уже легче читать
std::cout << «It is so exciting!» << std::endl;

// не так ли?
std::cout << «Yeah!» << std::endl;

1
2
3
4
5
6
7
8

// cout и endl находятся в библиотеке iostream

std::cout<<«Hello,world!»<<std::endl;

 
// теперь уже легче читать

std::cout<<«It isso exciting!»<<std::endl;

 
// не так ли?

std::cout<<«Yeah!»<<std::endl;

Как избежать проблем?

Как вы уже поняли, способа безопасно вставить Javascript в HTML нет. Но есть способы сделать Javascript безопасным для вставки в HTML (почувствуйте разницу). Правда для этого нужно быть предельно внимательным всё время, пока вы пишете что-то внутри тега <script>, особенно если вы вставляете любые данные с помощью шаблонизатора.

Во-первых, вероятность того, что у вас в исходном тексте (даже после минификации) не в строковых литералах встретятся символы крайне мала. Сами вы вряд ли напишете что-то такое, а если злоумышленник что-то сможет написать прямо в теге <script>, то внедрение этих символов будет беспокоить вас в последнюю очередь.

Остается проблема внедрения символов в строки. В этом случае, как и написано в спецификации, всего-то нужно заменить все «» на «», «» на «», а «» на «». Но беда в том, что если вы выводите какую-то структуру с помощью , то вряд ли вы захотите потом её распарсить еще раз, чтобы найти все строковые литералы и заэкранировать в них что-то. Так же не хочется советовать пользоваться другими пакетами для сериализации, где эта проблема уже учтена, потому что ситуации бывают разными, а защититься хочется всегда и решение должно быть универсальным. Поэтому я бы советовал экранировать символы / и ! с помощью обратного слеша уже после сериализации. Эти символы не могут встречаться в JSON нигде кроме как внутри строк, поэтому простая замена будет абсолютно безопасной. Это не изменит последовательность символов «», но она и не представляет опасности, если встречается сама по себе.

Точно так же можно экранировать и отдельные строки.

Другой совет — не встраивайте в тег <script> ничего вообще. Храните данные в местах, где трансформации для вставки данных однозначны и обратимы. Например, в атрибутах других элементов. Правда смотрится это довольно грязно и работает только со строками, JSON придется парсить отдельно.

Но, по-хорошему, конечно, если вы хотите нормально разрабатывать приложения, а не аккуратно ходить по минному полю, нужен надежный способ встраивания скриптов в HTML. Поэтому правильным решением считаю вообще отказаться от тега <script>, как от не безопасного.

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

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

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

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

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

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

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

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

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

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

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

Оцените статью
Рейтинг автора
5
Материал подготовил
Илья Коршунов
Наш эксперт
Написано статей
134
Добавить комментарий