This page has been robot translated, sorry for typos if any. Original content here.

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

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

Закомментировать код – значит написать комментарии в коде.

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

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

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

Комментарии в коде HTML

<!-- Для HTML -->

HTML (от англ. HyperText Markup Language — «язык гипертекстовой разметки») — стандартизированный язык разметки документов во Всемирной паутине. Большинство веб-страниц содержат описание разметки на языке HTML (или XHTML). Язык HTML интерпретируется браузерами; полученный в результате интерпретации форматированный текст отображается на экране монитора компьютера или мобильного устройства.

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

Пример с применением:

<html>
<head>
<title> Комментарии в коде HTML </title>
</head>
<body>
<!-- Шапка сайта -->
<img src="kartinka.png">
<!-- конец шапки сайта -->
</body>
</html>

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

/* 1. Многострочный комментарий для PHP */// 2. Однострочный комментарий для PHP# 3. Однострочный комментарий для PHP

PHP (англ. PHP: Hypertext Preprocessor — «PHP: препроцессор гипертекста»; первоначально Personal Home Page Tools — «Инструменты для создания персональных веб-страниц») — скриптовый язык общего назначения, интенсивно применяемый для разработки веб-приложений. В настоящее время поддерживается подавляющим большинством хостинг-провайдеров и является одним из лидеров среди языков, применяющихся для создания динамических веб-сайтов.

Язык и его интерпретатор (Zend Engine) разрабатываются группой энтузиастов в рамках проекта с открытым кодом. Проект распространяется под собственной лицензией, несовместимой с GNU GPL.

Пример с применением:

<?php
/* 1. Многострочный комментарий для PHP */
echo "Пример 1"; // 2. Однострочный комментарий для PHP
echo "Пример 2"; # 3. Однострочный комментарий для PHP
?>

Комментарии в коде CSS

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

CSS (англ. Cascading Style Sheets — каскадные таблицы стилей) — формальный язык описания внешнего вида документа, написанного с использованием языка разметки.

Преимущественно используется как средство описания, оформления внешнего вида веб-страниц, написанных с помощью языков разметки HTML и XHTML, но может также применяться к любым XML-документам, например, к SVG или XUL.

Пример с применением:

.p
{
font:25px "Times New Roman", Times, serif; /* Шрифт текста и размер */
}

Комментарии в коде JavaScript

// Однострочный комментарий для JavaScript/* Многострочный комментарий для JavaScript */

JavaScript (аббр. JS) — мультипарадигменный язык программирования. Поддерживает объектно-ориентированный, императивный и функциональный стили. Является реализацией языка ECMAScript (стандарт ECMA-262).

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

Пример с применением:

<script type="text/javascript">
/* Отсчет времени */
var RemainsSec = (parseInt(totalRemains/1000)); //сколько всего осталось секунд
var RemainsFullDays=(parseInt(RemainsSec/(24*60*60))); //осталось дней
/* Конец отсчет времени */
</script>

Комментарии в коде «.htaccess»

# Описание инструкции

.htaccess - конфигурационный файл веб-сервера Apache, позволяющий управлять работой веб-сервера и настройками сайта с помощью различных параметров (директив) без изменения основного конфигурационного файла веб-сервера.

Директивы файла .htaccess действуют для каталога, в котором размещён такой файл, и для всех его подкаталогов. Будьте, пожалуйста, внимательны при редактировании файла .htaccess! При сохранении такого файла в кодировке UTF-8 в нём не должно присутствовать BOM-сигнатуры.

Пример с применением:

# защита комментария от Спам-бота
RewriteEngine On
RewriteCond %{REQUEST_METHOD} POST

Via bloggood.ru & wiki

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

Как писать код сразу с комментариями

По сути говоря, принцип TDD (Test-driven development, разработка через тестирование) был перенесен на уровень ниже. Не помню как это звучало в оригинале, но по сути «Опиши комментариями структуру кода». На примере (сильно утрированном, почему — ниже) кода программы, складывающей два числа, этот принцип будет выглядеть так:

int main()
{
 // Принять от пользователя два числа
 // Завести переменную для результата сложения
 // Вернуть результат сложения

 return 0;
}

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

...
int main()
{
 double a,b;
 // Принять от пользователя два числа
 cin>>a;
 cin>>b;
 //Завести переменную для результата сложения
 double sum = a+b;
 // Вернуть результат сложения
 cout<<sum;

 return 0;
}

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

Как комментировать уже существующий код

Ответ на этот вопрос довольно прост: комментируем сущности от родителя к потомку: класс -> метод -> код внутри метода (если необходимо).

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

  • Совсем уж очевидные вещи. Комментарии вида // инициализируем счетчик бесят больше чем их отсутствие
  • Непонятный код дополнять комментарием типа // ничего не понял

Относительно второго пункта стоит немного пояснить и привести пример: вставка 100 строк ассемблера код на C! Вы на нее смотрите и пишите комментарий // Многа букаф! Ниасилил

После этого человек пришедший после вашего увольнения на ваше место видит этот комментарий и… все! Он даже не будет пытаться в нем разобраться и эта ваша запись будет клеймом на этом куске кода до тех пор пока его не уберут (либо код, либо комментарий).

Напоследок

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


Created/Updated: 25.05.2018

stop war in Ukraine

ukrTrident

stand with Ukraine