В W3Cast #3 Денис (  CurlyBrace) затронул тему использования styleguides, а у меня как раз уже была статья по этой теме. Поэтому я решил поделиться ей, чтобы показать наглядные примеры, демонстрирующих возможности «стилевых гидов».

«Стилевые гиды» — это свод правил и соглашений, предоставляющих разработчикам информацию о структуре кода и принятых правилах оформления. Чаще всего используется группой разработчиков, при совместном участии в проекте или же для самодисциплины при разработке кода.

Если проект большой, то он обрастает многочисленными файлами CSS с различными цветовыми схемами, типографикой и другими стилевыми установками. Чтобы избежать путаницы в структуре кода и не забыть что да как, нужно разрабатывать структурированный код, который впоследствии будет проще использовать, править и частично использовать в других проектах.

Лучший способ организации понятного кода — использование комментариев. Разработчики придумали весьма творческие способы использования комментариев и форматирования текста, чтобы улучшить понимание кода. Существует множество различных приемов, которые могут комбинироваться исходя из ваших предпочтений, но мы пока рассмотрим только несколько из них.

«Разделяй и властвуй»

Для начала проанализируйте структуру своего макета и выделите наиболее важные компоненты в CSS-коде. В большинстве случаев полезно рассортировать по принадлежности к классам или CSS-селекторам. Перед тем как начать «кодинг», объедините элементы в группы. Например, вы можете выделить глобальные стили («тело», параграфы, списки и т.д.), структуру, заголовки, текстовые стили, навигацию, формы, комментарии и отдельные элементы.

Выберите специальные метки (например, «звёздочку» — «*» или минус — «-») для того чтобы выделять важные элементы. Например ими можно выделять заголовки отдельх групп элементов. Очень немаловажно, чтобы метки бросались в глаза при беглом просмотре кода.

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

<code class="css">
/*
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[Master StyleSheet]

Project:	Obout.ru
Version:	1.1
Last change:	05/06/08 [fixed Float bug, Alex]
Assigned to:	Alexandr (ALex), Vasy Pupkin (VP)
Primary use:	OBOUT.RU
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*/
@import "reset.css";
@import "layout.css";
@import "colors.css";
@import "typography.css";
@import "flash.css";
/* @import "debugging.css"; */
</code>

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

Вдобавок можно включать отладочные диагностические CSS стили для поиска не корректных элементов.

Создание оглавления

Для описания структуры своего кода, можно сделать небольшое оглавление в начале стилевого файла. Этот прием поможет сделать краткий обзор структуры расположения элементов с использованием идентификаторов (ID) и классов (class) используемых в качестве отдельных веток структурного дерева страницы. Тутже можно использовать специальные ключевые слова для более быстрого поиска нужной секции в коде.

Например так:

<code class="css">
/*
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[Layout]

* body
	+ Header / #header
	+ Content / #content
		- Left column / #leftcolumn
		- Right column / #rightcolumn
		- Sidebar / #sidebar
			- RSS / #rss
			- Search / #search
			- Boxes / .box
			- Sideblog / #sideblog
	+ Footer / #footer

Navigation	  #navbar
Advertisements	  .ads
Content header	  h2
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*/
</code>

или же такой вариант которого я придерживаюсь:

<code class="css">
/*
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[Table of contents]

1. Body
	2. Header / #header
		2.1. Navigation / #navbar
	3. Content / #content
		3.1. Left column / #leftcolumn
		3.2. Right column / #rightcolumn
		3.3. Sidebar / #sidebar
			3.3.1. RSS / #rss
			3.3.2. Search / #search
			3.3.3. Boxes / .box
			3.3.4. Sideblog / #sideblog
			3.3.5. Advertisements / .ads
	4. Footer / #footer
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*/
</code>

Он позволяет осуществлять поиск по индексам и даёт схематическое представление о структуре страницы.

Есть ещё более простой способ который не использует вложенности, а использует обычный нумерованный список. Чтобы найти блок в стилевой таблице достаточно использовать файловый поиск и ввести цифру или название блока. Такой способ очень лёгок, быстр и эффективен.

<code class="css">
/*
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[Table of contents]

1. Body
2. Header / #header
3. Navigation / #navbar
4. Content / #content
5. Left column / #leftcolumn
6. Right column / #rightcolumn
7. Sidebar / #sidebar
8. RSS / #rss
9. Search / #search
10. Boxes / .box
11. Sideblog / #sideblog
12. Advertisements / .ads
13. Footer / #footer
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*/
<!-- здесь много CSS-кода -->

/*
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[8. RSS / #rss]
*/
#rss { ... }
#rss img { ... }
/*
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*/
</code>

Использование оглавления облегчит понимание и чтение вашего CSS-кода другим разработчикам. Его можно распечатать, чтобы оно было постоянно перед глазами, когда вы читаете код. Для работы в команде, использование оглавления станет хорошим преимуществом и сэкономит значительную часть вашего времени и времени ваших коллег.

Предустановка цветовой схемы и типографики

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

Одним из способов замены отсутствия констант заключается в том, чтобы создать определения некоторых констант, которые будут использоваться. Опять же это поможет избежать путаницы при копировании из одного свойства в другое. Если же решить изменить какое либо свойство в таблице стилей, достаточно опять же воспользоваться инструментами поиска и замены вашего редактора.

<code class="css">
/*
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# [Color codes]

# Dark grey (text): #333333
# Dark Blue (headings, links) #000066
# Mid Blue (header) #333399
# Light blue (top navigation) #CCCCFF
# Mid grey: #666666
#
*/
</code>

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

<code class="css">
/*
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[Color codes]

Background:	#ffffff (white)
Content:	#1e1e1e (light black)
Header h1:	#9caa3b (green)
Header h2:	#ee4117 (red)
Footer:		#b5cede (dark black)

a (standard):	#0040b6 (dark blue)
a (visited):	#5999de (light blue)
a (active):	#cc0000 (pink)
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*/
</code>

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

<code class="css">
/*
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[Typography]

Body copy:		1.2em/1.6em Verdana, Helvetica, Arial, Geneva, sans-serif;
Headers:		2.7em/1.3em Helvetica, Arial, "Lucida Sans Unicode", Verdana, sans-serif;
Input, textarea:	1.1em Helvetica, Verdana, Geneva, Arial, sans-serif;
Sidebar heading:	1.5em Helvetica, Trebuchet MS, Arial, sans-serif;

Notes:	decreasing heading by 0.4em with every subsequent heading level
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*/
</code>

Сортировка CSS свойств

Есть ещё несколько приемов для написания более структуированного и интуитивно понятного CSS-кода. Существует множество способов сортировки, придуманных разработчиками. Некоторые разработчики предпочитают размещать сначала цвета и шрифты; другие предпочитают сначала размещать более важные свойства, например, связанных с позиционированием элемента. Некоторые элементы также часто сортируют согласно структурному расположению или топологической схемы. К этому подходу можно отнести группировку селекторов тегов:

<code class="css">
    body,
	h1, h2, h3,
	p, ul, li,
	form {
		border: 0;
		margin: 0;
		padding: 0;
	}
</code>

Некоторые разработчики предпочитают сортирование свойства в алфавитном порядке:

<code class="css">
body {
	background: #fdfdfd;
	color: #333;
	font-size: 1em;
	line-height: 1.4;
	margin: 0;
	padding: 0;
}
</code>

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

Вложенность — ваш друг!

Использование табулировани селекторов сделает понимание кода более простым. Чем более «глубокий» элемент — тем большее количество табов ставится перед ним. Определите «родительский» элемент и отделите «дочерние» нужным количеством «табов»:

<code class="css">
#main-column { display: inline; float: left; width: 30em; }
		#main-column h1 { font-family: Georgia, "Times New Roman"; margin-bottom: 20px; }
		#main-column p { color: #333; }
</code>

Есть ещё один интересный подход киспользованию «табов» и комментариев. Иногда при внесении изменений результат оказывается не таким как вы ожидали. А что если изменений было сделано много и все их не запомнить? Вот тут то и может нам пригодиться выделение недавних изменений в вашем CSS-коде. Внесенные изменения можно помечать дополнительным отступом, который будет выделять свойство от других в этом же селекторе. Или же можно использовать некоторые ключевые слова в комментариях. Например @new, которое можно лекго найти и откатить внесенные изменения назад, до тех пор пока не найдете проблему.

<code class="css">
#sidebar ul li a {
     display: block;
     background-color: #ccc;
          border-bottom: 1px solid #999; /* @new */
     margin: 3px 0 3px 0;
          padding: 3px; /* @new */
}
</code>

Заключение

«Стилевые гиды» CSS могут быть полезны, если их использовать надлежащим образом. Не используйте «стилевые гиды», если они не позволяют вам получить лучшее понимание кода и лучшей структурированности кода. Ваша цель — достичь лучшей понимаемости/удобочитаемости кода.

PS. Не забывайте, что финальная версия ( или как говорят «продакшен») не должна содержать комментариев «стилевого гида», чтобы не нагружать пользователей передачей лишьнего объема данных. А у разработчика всё-таки должна быть полная версия и после завершения разработки.

Вольный перевод© по мотивам Improving Code Readability With CSS Styleguides

PPS. Спасибо всем кто поднял карму, перенёс в тематический блог.

UPD.В комментариях  vithar поделился своим CSS Code Style.

Предлагаю и остальным включаться и делиться своими наработками.

UPD. В комментариях уже профодил аналогию с phpdoc и вот наткнулся на начало реализации общего стандарта cssdoc — аналог phpdoc но уже для css. Развитие проекта поможет выработать более или менее единые стандарты при разработке css.