Вступ.
Тема нашого навчального матеріалу «Класифікація розділів @section в CSS» стосується попередньої теми «CSSDoc — cтандарт коментарів для CSS» і можна вважати її логічним продовженням. Отже ми продовжуємо вивчення формату CSSDoc для CSS коду. На перший погляд тема виглядає складною, але при уважному досідженні цього навчального матеріалу все стане на свої місця і стане зрозумілим. Коли ми починали писати перші рядки коду CSS, я просив Вас коментувати кожен рядок для кращого розуміння того, що ви пишете. І в цьому є певний сенс, про який ми з вами неодноразово говорили раніше. CSS необхідно коментувати, щоб потім було простіше зорієнтуватися собі чи тому, хто також підтримує чи надалі підтримуватиме ваш код. Але коментар біля кожного рядка це, звичайно, добре, але можна все це зробити набагато раціональніше, простіше та елегантніше. І тут нам знову стануть в наході ідеї з CSSDoc. Чому саме ідеї, а не сама спеціфікація, запитаєте ви? А тому, що проект Мета нашого заняття - підібрати необхідний мінімум опису секцій в CSS коді згідно стандартів CSSDoc. Отже ми не ставимо за мету повного дослідження стандартів CSSDoc, а лише тих моментів, які дозволять писати CSS код елегантно, зрозуміло і професійно.
Ми з вами вивчаємо, як правильно оформити CSS код.
Повторення.
Отже на першому етапі створення CSS файлу ми вносимо до нього опис секцій загальних стилів для сторінки і стилів для блоків сторінки. Давайте розглянемо приклад CSS коду, який нам нагадає структуру і сенс опису розділів:
Приклад CSS-коду з трьома секціями, описаними за допомогою CSSDoc:
/**
* Набір загальних стилів для сторінки.
*
* @author Петро Мироненко
* @version 1.0.0
* @license MIT
*/
/* Загальні стилі */
/**
* @section Body
*
* @description Цей розділ містить стилі, які застосовуються до всього елемента документа.
*
* @note Встановити колір тла, шрифт і поле основного тексту.
*
* @param {string} backgroundColor - Колір фону елемента .
* @param {string} fontFamily – сімейство шрифтів для тексту всередині елемента .
* @param {number} margin - зовнішній відступ навколо елемента .
*/
body {
background-color: #fff;
font-family: Arial, sans-serif;
margin: 0;
}
a {
color: #007bff;
text-decoration: none;
}
/* Секція стилів для шапки сайту */
/**
* @section Шапка сайту.
*
* @param {string} backgroundColor - Колір фону шапки.
* @param {string} color - Колір тексту в шапці.
* @param {number} padding - Розмір внутрішнього відступу шапки.
*
*/
.header {
background-color: #fff;
color: #333;
padding: 20px;
}
/* Секція стилів для футера */
/**
* @section Футер сайту.
*
* @description Цей розділ містить стилі для футера.
* @param {string} backgroundColor - Колір фону футера.
* @param {string} color - Колір тексту в футері.
* @param {number} padding - Розмір внутрішнього відступу футера
*/
.footer {
background-color: #333;
color: #fff;
padding: 20px;
}
У цьому прикладі ми бачимо три різні секції CSS-коду, кожна з яких описується за допомогою CSSDoc. Секція "Загальні стилі" описує загальні стилі для сторінки, а саме до всього елемента , такі як колір фону елемента, сімейство шрифтів для тексту всередині елемента, зовнішній відступ навколо елемента. Секція "Стилі шапки" описує стилі, пов'язані з шапкою сайту, такі як фон і колір тексту, а також розмір внутрішнього відступу. Секція "Стилі футера" описує стилі, пов'язані з футером сайту, такі як фон і колір тексту та внутрішні відступи. Кожна секція містить опис параметрів, які можна використовувати для кастомізації цих елементів.
Як бачимо з прикладу код зберігає максимальну елегантність при достатньому для розуміння опису розділів і коду.
Чи може бути два теги @description в описі секції?
В описі секції згідно CSSDoc не може бути двох або більше тегів @description. Кожен розділ може мати лише один тег @description, оскільки він призначений для короткого опису даного розділу. Якщо потрібно додатково описати розділ, можна використовувати тег @note або інші теги відповідно до їхнього призначення.
Послідовність розіділів.
Стандарт CSSDoc не має жорстких вимог щодо послідовності розділів. Проте, зазвичай рекомендується починати з загального опису в @description, а потім вказувати більш детальну інформацію в інших розділах, таких як @param, @example, @return та інші. Також рекомендується вказувати розділи в порядку їх використання в коді. Наприклад, якщо спочатку в коді йде опис властивостей, то відповідні розділи @param слід розміщувати першими. Але ці рекомендації не є обов'язковими і розміщення розділів може відрізнятися в залежності від специфіки проекту. Згідно стандарту CSSDoc, послідовність допустима у тому випадку, якщо вона відповідає правильному порядку секцій. Спочатку йде розділ (@section), потім опис (@description), далі можуть йти інші секції (наприклад, @note) і після цього параметри (@param).
У підсумку ми з вами продовжили ознайомлення з основними концепціями CSSDoc.
Класифікація розділів @section.
Класифікація розділів @section може бути здійснена як за блоками сторінки, так і за їх властивостями. Вибір залежить від конкретної ситуації та особливостей проекту.
Якщо ми класифікуємо розділи за блоками сторінки, то відповідні розділи можуть бути названі, наприклад, "header", "main", "footer", "sidebar", "navigation", "breadcrumbs" тощо. Така класифікація допоможе швидко знайти необхідний розділ при роботі зі сторінкою або її компонентами.
З іншого боку, якщо ми класифікуємо розділи за їх властивостями, то відповідні розділи можуть бути названі, наприклад, "typography", "colors", "spacing", "layout", "animation" тощо. Така класифікація дозволяє швидко знайти необхідні стилі при редагуванні властивостей сторінки або компонентів.
В будь-якому випадку, важливо дотримуватися узгодженості та створювати зрозумілу для всіх учасників проекту структуру розділів @section.
Яка класифікація більш доцільна, чи оптимальна?
Обидва підходи мають свої переваги і недоліки, тому вибір залежить від конкретної ситуації і особистих уподобань розробника.
Класифікація розділів @section за блоками сторінки може бути корисною для більших проектів, де код складається з багатьох сторінок. В такому випадку розділи можуть відповідати різним частинам сторінки, таким як шапка, основний контент, підвал і т. д. Це може зробити код більш організованим і легким для розуміння.
Класифікація за властивостями може бути корисною для менших проектів або проектів, які мають одну сторінку. Розділи можуть відповідати різним властивостям CSS, таким як кольори, шрифти, розміри і т. д. Це може допомогти зберігати CSS більш організованим і легким для редагування.
Якщо менший проект становиться з часом більшим проектом, то чи логічно припустити, що потрібно і в меншому проекті робити класифікацію за блоками?
Якщо відомо, що проект буде зростати, то варто зразу ж працювати з підходом до класифікації розділів @section за блоками сторінки. Такий підхід забезпечує зручність та логіку управління стилів, які стосуються конкретного блоку. Це спрощує роботу з CSS у великих проектах, де кількість стилів може бути дуже великою.
Навіть у менших проектах варто застосовувати цей підхід, оскільки він забезпечує зручну організацію коду, яку можна легко розширити в майбутньому. В процесі розвитку проекту може виникнути потреба у зміні дизайну окремих блоків, і якщо розділи @section вже були класифіковані за блоками сторінки, то зміни в логіці стилів будуть зручнішими та швидкими.
Основні концепції CSSDoc:
- CSSDoc - це документаційна система для CSS, яка дозволяє детально описувати різні розділи CSS коду з метою поліпшення розуміння коду та зручності для тих, хто працює з ним. Деякі з основних концепцій CSSDoc включають:
- Розділи (@section): CSSDoc дозволяє розділяти код на різні частини, що мають свою назву. Це дозволяє легше орієнтуватись в CSS файлі та швидше знаходити необхідний розділ.
- Описи (@description): Це розділ документації, де можна детально описати, що робить даний розділ CSS коду. Опис допомагає іншим розуміти код та використовувати його правильно.
- Параметри (@param): Це розділ документації, де можна описати параметри, що використовуються в розділі CSS коду. Це допомагає зрозуміти, які значення можна використовувати та як вони впливають на розділ.
- Примітки (@note): Це розділ документації, де можна вказати додаткову інформацію про розділ CSS коду. Це можуть бути примітки щодо зв'язку з іншими розділами, особливостями використання та інші.
- Приклади (@example): Це розділ документації, де можна додати приклади використання розділу CSS коду. Це допомагає іншим розуміти, як правильно використовувати даний розділ коду.
Загалом, CSSDoc є потужним інструментом для документування CSS коду та поліпшення комунікації між розробниками. Використання CSSDoc може зменшити кількість помилок та збільшити продуктивність при роботі з CSS файлами.
Використані джерела:
- https://github.com/cssdoc/cssdoc
- http://web.archive.org/web/20130701094049/http://cssdoc.net/
- http://web.archive.org/web/20111123094013/http://cssdoc.net/wiki/CssdocDraft
З повагою, Юрій Чернієвський! Керівник гуртка "WEB-Miditaur" науково – технічного напряму «WEB технології» ЦДЮТ Краснопільської селищної ради. Бакалавр, прикладна математика за спеціальним напрямом інформатика, Спеціаліст - інформатика, математик - програміст.
Мої побажання
Будь допитливим, досліджуй глибини понять, адже лише це і допомагає розвиватися! На цьому сайті формується сприятливий простір для вивчення web. Рівень твого самостійного заглиблення в певні питання сьогодні будуть відповідати рівню твоєї компетенції з даного питання в майбутньому. Єдиним фактором, який має значення, є твоя власна здатність і бажання вчитися. Немає сенсу порівнювати свій прогрес з іншими, оскільки цей досвід здебільшого суб’єктивний. Поділіться посиланням у соціальних мережах за допомогою кнопок, розміщених нижче та підпишіться на блог, щоб першими отримувати нові публікації корисного навчального контенту!
Коментуй публікацію, пиши свої враження, залишай питання в коментарях, якщо якісь моменти з публікації залишилися не зрозумілими!вихованцям
0 Коментарів Підписатися на цей блог