CSSDoc — cтандарт коментарів для CSS

Юрій Чернієвський 3 хвилини читання

CSSDoc - це стандарт коментування CSS-коду, який допомагає розробникам зберігати код зрозумілим і легко зрозумілим для інших розробників. Коментарі, написані відповідно до CSSDoc, дозволяють розробникам описувати структуру, функціональність та параметри CSS-коду, що полегшує його розуміння та редагування. В результаті цього код стає більш зрозумілим та доступним для розробників інших проектів, які можуть приєднатися до роботи над проектом в майбутньому.

Рекомендації CSSDoc щодо організації CSS-коду та коментарів до нього.

  • Використовуйте логічну структуру для організації CSS-коду за допомогою селекторів та комбінаторів.
  • Використовуйте коментарі для пояснення структури та призначення блоків CSS-коду.
  • Використовуйте коментарі, щоб описати роль та функцію кожного класу, ID, атрибута, псевдокласу та псевдоелемента.
  • Використовуйте коментарі, щоб описати специфічні атрибути CSS, які використовуються в конкретному блоку CSS-коду.
  • Використовуйте коментарі для пояснення будь-яких незрозумілих або складних рішень, що використовуються в CSS.
  • Використовуйте коментарі, щоб зафіксувати зміни в CSS-коді та пояснити причини цих змін.
  • Використовуйте коментарі для пояснення кросс-браузерних проблем та забезпечення сумісності з різними браузерами.
  • Використовуйте коментарі для пояснення будь-яких виключень або винятків, які застосовуються до певних елементів.

Зверніть увагу, що CSSDoc не є стандартом CSS, але це документаційний формат, який можна використовувати для документування CSS-коду.

Нижче наведено приклад створення пустого CSS файлу з коментарями, які відповідають формату CSSDoc:

Приклад пустого CSS файлу з коментарями, які відповідають формату CSSDoc:

/**
 * Назва проекту / файлу
 * @description Опис проекту / файлу
 *
 * @version 1.0.0
 *
 * @author Ім'я автора
 * @created Дата створення
 * @updated Дата останнього оновлення
 */

/*------------------------------------*\
    #SECTION-1
\*------------------------------------*/

/**
 * @section Секція 1
 * @description Опис секції 1
 */

/*------------------------------------*\
    #SECTION-2
\*------------------------------------*/

/**
 * @section Секція 2
 * @description Опис секції 2
 */

/*------------------------------------*\
    #SECTION-3
\*------------------------------------*/

/**
 * @section Секція 3
 * @description Опис секції 3
 */

У цьому прикладі створено пустий файл з трьома секціями, кожна з яких містить коментар з описом секції. Використовуються теги CSSDoc, такі як @section і @description, для опису секцій та їх змісту. Також додані загальні коментарі для опису проекту, версії, автора та дати створення та останнього оновлення. Це допомагає зрозуміти, що робить файл та як його використовувати.
Давайте розглянемо ще один приклад CSS файлу з коментарями згідно стандартів CSSDoc, який містить прості зразки коду:

Приклад вмісту css файлу з коментарями згідно стандартів CSSDoc з простими зразками коду:

/**
 * @description Простий файл CSS для стилізації елемента кнопки
 * @author Катерина Шевченко
 * @license MIT
 * @version 1.0
 */

/* Стилі кнопок */

/**
 * @description Встановлює базові стилі для елемента кнопки
 * @param {string} color - Колір фону кнопки
 * @param {string} font-size - Розмір шрифту тексту кнопки
 * @param {string} padding - Підкладка навколо кнопки
 */
.button {
  background-color: #007bff;
  color: #fff;
  font-size: 16px;
  padding: 12px 24px;
  border: none;
  border-radius: 4px;
}

/**
 * @description SВстановлює стилі наведення курсора для елемента кнопки
 * @param {string} color - Колір фону кнопки при наведенні
 */
.button:hover {
  background-color: #0069d9;
}

/**
 * @description Встановлює активні стилі для елемента кнопки
 * @param {string} color - Колір фону кнопки активний
 */
.button:active {
  background-color: #005cbf;
}

У цьому прикладі ми маємо CSS файл, який містить стилі для елемента кнопки. Ми додали коментарі до кожного селектора, щоб пояснити, які стилі вони задають та які параметри вони очікують. В коментарі до .button ми використовуємо теги @description та @param для пояснення базових стилів кнопки та передачі параметрів, таких як колір, розмір шрифту та відступи. В коментарях до .button:hover та .button:active ми використовуємо тег @description для пояснення стилів, які будуть застосовані під час наведення та активування кнопки. Ми також передаємо параметр color, щоб пояснити, який колір буде застосований. У коментарі до файлу ми також використали теги @author, @license та @version, щоб вказати автора, ліцензію та номер версії файлу.

Використані джерела: