CSS GuideLines, частина 2. Коментування коду

       
 
В кожному проекті є певні нюанси і тонкощі, які пам'ятають далеко не все, і найгірше, що може трапитися з розробником — це робота з кодом, який писав не він. Навіть запам'ятовування тонкощів свого власного коду є можливим тільки до певної міри, не кажучи вже про чужий коді. Саме тому CSS треба коментувати .
 
CSS це декларативний мову, і часто буває важко зрозуміти:
 
     
  • Що якийсь шматок коду залежить від іншого шматка;
  •  
  • Який ефект спричинить зміну певної частини коду;
  •  
  • Де ще можна використовувати шматок коду без появи нових проблем;
  •  
  • Які стилі успадковує певний елемент;
  •  
  • Які стилі можуть бути проігноровані;
  •  
  • Де розробник мав намір використовувати код.
  •  
Цей список навіть не зачіпає багатьох примх CSS, таких як включення апаратного прискорення за допомогою свойтсва
transform
, а адже такі речі теж ускладнюють розуміння того, що робить код.
 
Так як CSS сам по собі не може бути достатньо зрозумілим, то розробники дійсно отримують вигоду від коментування коду.
 
Як правило, слід коментувати ті місця коду, які будуть незрозумілі розробнику, якщо вирвати їх з контексту. Немає необхідності робити позначку про те, що
color: red;
зробить текст червоним. Але, наприклад, якщо ви використовуєте властивість
overflow: hidden;
для очистки float'ов, а не для приховування контенту за межами блоку, то вам слід було б додати пояснювальний коментар.
 
 

Високорівневі коментарі

Для великих коментарів, що описують цілу секцію або компонент, ми використовуємо DocBlock-подібні мультістрочние коментарі, відповідають нашому правилу про 80 ​​символах в рядку.
 
Нижче можна побачити реальний приклад коментування коду шапки сайту CSSWizardy.
 
 
/**
 * The site’s main page-head can have two different states:
 *
 * 1) Regular page-head with no backgrounds or extra treatments; it just
 *    contains the logo and nav.
 * 2) A masthead that has a fluid-height (becoming fixed after a certain point)
 *    which has a large background image, and some supporting text.
 *
 * The regular page-head is incredibly simple, but the masthead version has some
 * slightly intermingled dependency with the wrapper that lives inside it.
 */

Цей рівень коментування повинен використовуватися для опису елемента в загальному: його стану, від чого цей стан залежить тощо.
 
 
Вказівка ​​на спадкування стилів
Коли ви працюєте з великою кількістю файлів, то не завжди набори правил, що відносяться один до одного, будуть знаходитися в одному і тому ж файлі. Наприклад, у вас може бути головний клас
.btn
, що містить в собі тільки основні стилі кнопки (розміри і відступи, наприклад). Цей клас розширюється в файлі компонентів, там в нього додаються стилі для додання потрібного зовнішнього вигляду. Ці зв'язки між об'єктами ми повинні позначити за допомогою вказівки на успадкування стилів.
 
Наприклад, у файлі з головним класами (об'єктами):
 
 
/**
 * Extend `.btn {}` in _components.buttons.scss.
 */

.btn {}

У файлі з дочірніми класами:
 
 
/**
 * These rules extend `.btn {}` in _objects.buttons.scss.
 */

.btn--positive {}

.btn--negative {}

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

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

Часто нам потрібно прокоментувати певну рядок коду з оголошенням якої-небудь властивості. Для цього ми використовуємо виноски. За посиланням можна побачити приклад складнішого коментування коду шапки сайту, про яку йшлося вище. Такий спосіб коментування дозволяє нам тримати всю документацію в одному місці, і потім всього лише посилатися на потрібне місце в документації, замість того, щоб писати довгий коментар прямо в коді.
 
 

препроцесорів і коментування

У багатьох, якщо не у всіх препроцесорів є можливість додавати коментарі, які при компіляції НЕ будуть виводитися в підсумковий файл стилів. Прийміть за правило використовувати такі коментарі для коду, який також не буде скомпільований. Для коду, який буде виведений в підсумковий файл, використовуйте звичайні коментарі.
 
Так правильно:
 
 
// Dimensions of the @2x image sprite:
$sprite-width:  920px;
$sprite-height: 212px;

/**
 * 1. Default icon size is 16px.
 * 2. Squash down the retina sprite to display at the correct size.
 */
.sprite {
    width:  16px; /* [1] */
    height: 16px; /* [1] */
    background-image: url(/img/sprites/main.png);
    background-size: ($sprite-width / 2 ) ($sprite-height / 2); /* [2] */
}

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

Видалення коментарів

Слід сказати про те, що при використанні коду в продакшені всі коментарі повинні бути видалені, а сам CSS повинен бути мініфіцірован перед деплоем.
 
Попередня частина: CSS GuideLines, частина 1.Сінтаксіс і форматування
  
Джерело: Хабрахабр

0 коментарів

Тільки зареєстровані та авторизовані користувачі можуть залишати коментарі.