---

layout: default

---

<div class="heading" id="toc">

<h2>Оглавление</h2>

<div class="section toc">

<div class="col">

<h4><a href="#html">HTML</a></h4>

<ul>

<li><a href="#html-syntax">Синтаксис</a></li>

<li><a href="#html-doctype">HTML5 doctype</a></li>

<li><a href="#html-encoding">Кодировка символов</a></li>

<li><a href="#html-style-script">Подключение CSS и JavaScript</a></li>

<li><a href="#html-practicality">Практичность важнее чистоты</a></li>

<li><a href="#html-attribute-order">Порядок атрибутов</a></li>

<li><a href="#html-boolean-attributes">Логические атрибуты</a></li>

<li><a href="#html-reducing-markup">Сокращение разметки</a></li>

<li><a href="#html-javascript">Разметка, генерируемая с помощью JavaScript</a></li>

</ul>

</div>

<div class="col">

<h4><a href="#css">CSS</a></h4>

<ul>

<li><a href="#css-syntax">CSS синтаксис</a></li>

<li><a href="#css-declaration-order">Порядок объявления</a></li>

<li><a href="#css-media-queries">Место для media query</a></li>

<li><a href="#css-prefixed-properties">Свойства с префиксами</a></li>

<li><a href="#css-single-declarations">Правила с одиночными объявлениями</a></li>

<li><a href="#css-shorthand">Сокращенная запись</a></li>

<li><a href="#css-nesting">Вложенность в Less и Sass</a></li>

<li><a href="#css-comments">Комментарии</a></li>

<li><a href="#css-classes">Имена классов</a></li>

<li><a href="#css-selectors">Селекторы</a></li>

<li><a href="#css-organization">Организация кода</a></li>

</ul>

</div>

<div class="section" id="golden-rule">

<div class="col">

<h2>Золотое правило</h2>

<p>Всегда соблюдайте приведенные здесь или свои собственные согласованные руководства. Сообщите, если найдете ошибку, будь она маленькая или большая. Для дополнений или участия в этом руководстве, пожалуйста, <a href="https://github.com/mdo/code-guide/issues/new">создайте issue на GitHub</a>.</p>

</div>

<div class="col">

<blockquote>

<p>Каждая строка кода должна казаться написанной только одним человеком, вне зависимости от количества разработчиков.</p>

</blockquote>

</div>

<div class="heading" id="html">

<h2>HTML</h2>

<div class="section" id="html-syntax">

<div class="col">

<h3>Синтаксис</h3>

<ul>

<li>Используйте мягкие отступы с двумя символами пробела &mdash; это единственный способ, гарантирующий, что ваш код будет одинаково выглядеть в любом случае.</li>

<li>Вложенные элементы должны иметь отступ (два пробела).</li>

<li>В атрибутах всегда используйте двойные ковычки и никогда не используйте одинарные.</li>

<li>Не добавляйте слэш ("/") в конец одиночного тега &mdash; <a href="http://dev.w3.org/html5/spec-author-view/syntax.html#syntax-start-tag">Спецификация HTML5 </a> говорит, что это необязательно.</li>

<li>Не пропускайте необязательные закрывающие теги (например, <code>&lt;/li&gt;</code> или <code>&lt;/body&gt;</code>).</li>

</ul>

</div>

<div class="col">

{% highlight html %}{% include html/syntax.html %}{% endhighlight %}

</div>

<div class="section" id="html-doctype">

<div class="col">

<h3>HTML5 doctype</h3>

<p>Указав этот простой doctype в самом начале каждой вашей HTML-страницы, вы сможете соблюсти standards mode (режим соответствия стандартам) и наиболее верное отображение в любом возможном браузере.</p>

</div>

<div class="col">

{% highlight html %}{% include html/doctype.html %}{% endhighlight %}

</div>

<div class="section" id="html-encoding">

<div class="col">

<h3>Кодировка символов</h3>

<p>Чтобы быстро и легко обеспечить правильное отображение вашего контента, явно объявляйте кодировку символов.</p>

</div>

<div class="col">

{% highlight html %}{% include html/encoding.html %}{% endhighlight %}

</div>

<div class="section" id="html-style-script">

<div class="col">

<h3>Подключение CSS и JavaScript</h3>

<p>Согласно спецификации HTML5, обычно не требуется указание атрибута <code>type</code> при подключении CSS и JavaScript файлов, так как <code>text/css</code> и <code>text/javascript</code> являются значениями по умолчанию.</p>

<h4>Ссылки на спецификацию HTML5:</h4>

<ul>

<li><a href="http://www.w3.org/TR/2011/WD-html5-20110525/semantics.html#the-link-element">Использование тега link</a></li>

<li><a href="http://www.w3.org/TR/2011/WD-html5-20110525/semantics.html#the-style-element">Использование тега style</a></li>

<li><a href="http://www.w3.org/TR/2011/WD-html5-20110525/scripting-1.html#the-script-element">Использование тега script</a></li>

</ul>

</div>

<div class="col">

{% highlight html %}{% include html/style-script.html %}{% endhighlight %}

</div>

<div class="section" id="html-practicality">

<div class="col">

<h3>Практичность важнее чистоты</h3>

<p>Старайтесь поддерживать стандарты HTML и семантику, но не за счет практичности. Используйте меньшее количество разметки с наименьшим числом тонкостей, когда это возможно.</p>

</div>

<div class="section" id="html-attribute-order">

<div class="col">

<h3>Порядок атрибутов</h3>

<p>Для удобства чтения HTML-атрибуты должны быть указаны в определенном порядке:</p>

<ul>

<li><code>class</code></li>

<li><code>id</code>, <code>name</code></li>

<li><code>data-*</code></li>

<li><code>src</code>, <code>for</code>, <code>type</code>, <code>href</code></li>

<li><code>title</code>, <code>alt</code></li>

<li><code>aria-*</code>, <code>role</code></li>

</ul>

<p>Классы создают для многократно используемых компонентов, поэтому они идут первыми. Идентификаторы более специфичны и должны использоваться умеренно (например, для закладок на странице), поэтому они следуют вторыми.</p>

</div>

<div class="col">

{% highlight html %}{% include html/attribute-order.html %}{% endhighlight %}

</div>

<div class="section" id="html-boolean-attributes">

<div class="col">

<h3>Логические атрибуты</h3>

<p>A boolean attribute is one that needs no declared value. XHTML required you to declare a value, but HTML5 has no such requirement.</p>

<p>For further reading, consult the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/common-microsyntaxes.html#boolean-attributes">WhatWG section on boolean attributes</a>:</p>

<blockquote>

<p>The presence of a boolean attribute on an element represents the true value, and the absence of the attribute represents the false value.</p>

</blockquote>

<p>If you <em>must</em> include the attribute's value, and <strong>you don't need to</strong>, follow this WhatWG guideline:</p>

<blockquote>

<p>If the attribute is present, its value must either be the empty string or [...] the attribute's canonical name, with no leading or trailing whitespace.</p>

</blockquote>

<p><strong>In short, don't add a value.</strong></p>

</div>

<div class="col">

{% highlight html %}{% include html/boolean-attributes.html %}{% endhighlight %}

</div>

<div class="section" id="html-reducing-markup">

<div class="col">

<h3>Сокращение разметки</h3>

<p>Всякий раз, когда это возможно, избегайте лишних родительских элементов при написании HTML. Во многих случаях это требует повторения и рефакторинга, но создает меньше HTML-разметки. Посмотрите на следующий пример:</p>

</div>

<div class="col">

{% highlight html %}{% include html/reducing-markup.html %}{% endhighlight %}

</div>

<div class="section" id="html-javascript">

<div class="col">

<h3>Разметка, генерируемая с помощью JavaScript</h3>

<p>Написание разметки в JavaScript-файлах делает ее сложной для поиска, сложной для редактирования и менее производительной. По возможности, избегайте этого.</p>

</div>

<div class="heading" id="css">

<h2>CSS</h2>

<div class="section" id="css-syntax">

<div class="col">

<h3>Синтаксис</h3>

<ul>

<li>Используйте мягкие отступы с двумя символами пробела &mdash; это единственный способ, гарантирующий, что ваш код будет одинаково выглядеть в любом случае.</li>

<li>При группировке селекторов помещайте каждый селектор на отдельную строку.</li>

<li>Для лучшей читаемости оставляйте один пробел перед открывающейся фигурной скобкой блока объявлений.</li>

<li>Помещайте закрывающуюся фигурную скобку блока объявлений на новой строке.</li>

<li>Оставляйте один пробел после <code>:</code> для каждого объявления.</li>

<li>Каждое объявление должно находится на отдельной строке для более точного сообщения об ошибках.</li>

<li>Заканчивайте все объявления точкой с запятой. Для последнего объявления в блоке это не является обязательным, но ваш код будет более подвержен ошибкам.</li>

<li>Для свойств, значения которых разделены запятыми, следуюет оставлять по одному пробелу после каждой запятой (например, <code>box-shadow</code>).</li>

<li>Не оставляйте пробелов после запятых <em>внтури</em> значений <code>rgb()</code>, <code>rgba()</code>, <code>hsl()</code>, <code>hsla()</code>, или <code>rect()</code>. Это помогает различать различные цветовые значения (запятая без пробела) от нескольких значений одного свойства (запятая с пробелом). Так же не добавляйте начальный ноль для значений (например, <code>.5</code> вместо <code>0.5</code>).</li>

<li>Все 16-ичные значения записывайте строчными буквами (в нижнем регистре), например, <code>#fff</code>. Строчные буквы гораздо легче различить при сканировании документа, поскольку они, как правило, имеют больше уникальных форм.</li>

<li>Используйте короткие 16-ичные значения везде, где это возможно, например, <code>#fff</code> вместо <code>#ffffff</code>.</li>

<li>Всегда берите в кавычки значения атрибутов внутри селектора, например, <code>input[type="text"]</code>. <a href="http://mathiasbynens.be/notes/unquoted-attribute-values#css">В некоторых случаях это делать необязательно</a>, но это является хорошей практикой для поддержки согласованности.</li>

<li>Опускайте единицы измерения при нулевом значении, например, <code>margin: 0;</code> вместо <code>margin: 0px;</code>.</li>

</ul>

<p>Есть вопросы по перечисленным утверждениям? Ознакомьтесь с <a href="http://en.wikipedia.org/wiki/Cascading_Style_Sheets#Syntax">разделом о синтаксисе статьи о каскадных таблицах стилей</a> на Википедии.</p>

</div>

<div class="col">

{% highlight css %}{% include css/syntax.css %}{% endhighlight %}

</div>

<div class="section" id="css-declaration-order">

<div class="col">

<h3>Порядок объявления</h3>

<p>Объявления связанных свойств должны быть сгруппированы по следующему порядку:</p>

<ol>

<li>Позиционирование</li>

<li>Блочная модель</li>

<li>Типографика</li>

<li>Отображение</li>

</ol>

<p>Позиционирование следует первым потому, что оно может удалить элемент из нормального потока документа и переопределить блочную модель связанных стилей. Блочная модель идет следующей, так как она диктует размеры и расположение компонента.</p>

<p>Все остальное, выполняющееся <em>внутри</em> компонента или не оказывающее влияния на предыдущие два раздела, идет в последнюю очередь.</p>

<p>Для полного списка свойств и их порядка, пожалуйста, ознакомьтесь с <a href="http://twitter.github.com/recess">Recess</a>.</p>

</div>

<div class="col">

{% highlight css %}{% include css/declaration-order.css %}{% endhighlight %}

</div>

<div class="section" id="css-media-queries">

<div class="col">

<h3>Место для media query</h3>

<p>Помещайте media queries настолько близко к соответствующим наборам правил, насколько это возможно. Не объединяйте их в отдельную таблицу стилей. Не помещайте их в конце документа. В противном случае это приведет к тому, что media queries будут не замечены в будущем. Вот типичная структура.</p>

</div>

<div class="col">

{% highlight css %}{% include css/media-queries.css %}{% endhighlight %}

</div>

<div class="section" id="css-prefixed-properties">

<div class="col">

<h3>Свойства с префиксами</h3>

<p>Когда вы используете свойства с префиксами вендоров, делайте отступы для каждого свойства так, чтобы значения объявлений образовывали вертикальную линию. Это упрощает многострочное редактирование.</p>

<p>В Textmate используйте <strong>Text &rarr; Edit Each Line in Selection</strong> (&#8963;&#8984;A). В Sublime Text 2, используйте <strong>Selection &rarr; Add Previous Line</strong> (&#8963;&#8679;&uarr;) и <strong>Selection &rarr; Add Next Line</strong> (&#8963;&#8679;&darr;).</p>

</div>

<div class="col">

{% highlight css %}{% include css/prefixed-properties.css %}{% endhighlight %}

</div>

<div class="section" id="css-single-declarations">

<div class="col">

<h3>Правила с одиночными объявлениями</h3>

<p>В случаях, когда набор правил включает в себя <strong>только одно объявление</strong>, рекомендуется удалить переносы строк для удобства чтения и редактирования. Любой набор правил с несколькими объявлениями должен быть разделен на отдельные строки.</p>

<p>Ключевым фактором здесь является обнаружение ошибок &mdash; например, валидатор CSS сообщает вам, что в строке 183 есть синтаксическая ошибка. С одиночным объявлением не возникнет сложности с исправлением. В случае с несколькими объявлениями, разделенными на строки, так же проблем не возникнет. Но если несколько объявлений будут записаны в одну строку, то вам будет сложнее понять какое именно объявление вызвало синтаксическую ошибку.</p>

</div>

<div class="col">

{% highlight css %}{% include css/single-declarations.css %}{% endhighlight %}

</div>

<div class="section" id="css-shorthand">

<div class="col">

<h3>Сокращенная запись</h3>

<p>Старайтесь ограничить использование сокращенных объявлений в тех случаях, когда необходимо явно задать все доступные значения. Наиболее часто злоупотребляют сокращением следующих свойств:</p>

<ul>

<li><code>padding</code></li>

<li><code>margin</code></li>

<li><code>font</code></li>

<li><code>background</code></li>

<li><code>border</code></li>

<li><code>border-radius</code></li>

</ul>

<p>Часто нам не нужно устанавливать все значения сокращенной записи свойства. Например, HTML заголовки устанавливают только отступы сверху и снизу, таким образом, в случае необходимости нужно будет переопределить только эти два значения. Чрезмерное использование сокращенной записи свойств часто приводит к грязному коду с ненужными переопределения и непреднамеренными побочными эффектами.</p>

<p>На сайте Mozilla Developer Network есть отличная статья о <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties">сокращенной записи свойств</a> для тех кто с ней не знаком.</p>

</div>

<div class="col">

{% highlight css %}{% include css/shorthand.css %}{% endhighlight %}

</div>

<div class="section" id="css-nesting">

<div class="col">

<h3>Вложенность в Less и Sass</h3>

<p>Избегайте излюшнюю вложенность. Просто потому, что вы можете ее использователь, не означает, что вы всегда должны это делать. Consider nesting only if you must scope styles to a parent and if there are multiple elements to be nested.</p>

</div>

<div class="col">

{% highlight scss %}{% include css/nesting.scss %}{% endhighlight %}

</div>

<div class="section" id="css-comments">

<div class="col">

<h3>Комментарии</h3>

<p>Код написан и поддерживается людьми. Убедитесь, что ваш код является описательным, хорошо прокомментирован и доступным (понятным) для других. Хорошие комментарии к коду передают контекст и цель кода, а не просто повторяют название класса или компонента.</p>

<p>Обязательно пишите законченные предложения для больших комментариев и короткие фразы для общих замечаний.</p>

</div>

<div class="col">

{% highlight css %}{% include css/comments.css %}{% endhighlight %}

</div>

<div class="section" id="css-classes">

<div class="col">

<h3>Имена классов</h3>

<ul>

<li>Keep classes lowercase and use dashes (not underscores or camelCase). Dashes serve as natural breaks in related class (например, <code>.btn</code> и <code>.btn-danger</code>).</li>

<li>Избегайте чрезмерные и произвольные сокращения. <code>.btn</code> подойдет для <em>button</em>, но <code>.s</code> не означает ничего.</li>

<li>Keep classes as short and succinct as possible.</li>

<li>Используйте осмысленные имена; use structural or purposeful names over presentational.</li>

<li>Prefix classes based on the closest parent or base class.</li>

<li>Используйте имена классов с префиксом <code>.js-*</code> для обозначения поведения (в отличие от стиля), но не используйте эти классы в вашем CSS.</li>

</ul>

</div>

<div class="col">

{% highlight css %}{% include css/class-names.css %}{% endhighlight %}

</div>

<div class="section" id="css-selectors">

<div class="col">

<h3>Селекторы</h3>

<ul>

<li>Use classes over generic element tag for optimum rendering performance.</li>

<li>Avoid using several attribute selectors (e.g., <code>[class^="..."]</code>) on commonly occuring components. Browser performance is known to be impacted by these.</li>

<li>Keep selectors short and strive to limit the number of elements in each selector to three.</li>

<li>Scope classes to the closest parent <strong>only</strong> when necessary (e.g., when not using prefixed classes).</li>

</ul>

<p>Дополнительно к прочтению:</p>

<ul>

<li><a href="http://markdotto.com/2012/02/16/scope-css-classes-with-prefixes/">Scope CSS classes with prefixes</a></li>

<li><a href="http://markdotto.com/2012/03/02/stop-the-cascade/">Stop the cascade</a></li>

</ul>

</div>

<div class="col">

{% highlight css %}{% include css/selectors.css %}{% endhighlight %}

</div>

<div class="section" id="css-organization">

<div class="col">

<h3>Организация кода</h3>

<ul>

<li>Organize sections of code by component.</li>

<li>Develop a consistent commenting hierarchy.</li>

<li>Use consistent white space to your advantage when separating sections of code for scanning larger documents.</li>

<li>When using multiple CSS files, break them down by component instead of page. Pages can be rearranged and components moved.</li>

</ul>

</div>

<div class="col">

{% highlight css %}{% include css/organization-comments.css %}{% endhighlight %}

</div>

<div class="section" id="css-editor-prefs">

<div class="col">

<h3>Настройки редактора кода</h3>

<p>Set your editor to the following settings to avoid common code inconsistencies and dirty diffs:</p>

<ul>

<li>Use soft-tabs set to two spaces.</li>

<li>Trim trailing white space on save.</li>

<li>Установите кодировку файлов UTF-8.</li>

<li>Add new line at end of files.</li>

</ul>

<p>Consider documenting and applying these preferences to your project's <code>.editorconfig</code> file. For an example, see <a href="https://github.com/twbs/bootstrap/blob/master/.editorconfig">the one in Bootstrap</a>. Learn more <a href="http://editorconfig.org">about EditorConfig</a>.</p>

</div>