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! Ви на неї дивитеся і пишіть коментар // Многа букаф! ніасіліл

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

наостанок

На закінчення можу сказати, що мистецтво написання коментарів є невід'ємною частиною мистецтва програмування, тому коментарі писати треба, і, як би пафосно це не звучало, але написання якісних коментарів треба вчитися.