HTML Style Guide - Lebedancer/component-example GitHub Wiki
- Общие правила оформления
- Общие правила форматирования
- Общие мета правила
- Правила оформления HTML
- Правила форматирования HTML
Не указывайте протокол при включении ресурсов на страницу.
Опускайте название протокола (http:, https:) в ссылках на картинки или другие медиа-ресурсы, файлы стилей или скрипты, если эти файлы не доступны по обоим протоколам.
Отсутствие протокола делает ссылку относительной, что предотвращает смешивание ресурсов из разных протоколов и незначительно уменьшает размер файлов.
<!-- плохо -->
<script src="http://www.google.com/js/gweb/analytics/autotrack.js"></script>
<!-- хорошо-->
<script src="//www.google.com/js/gweb/analytics/autotrack.js"></script>
/* плохо */
.example {
background: url(http://www.google.com/images/example);
}
/* хорошо */
.example {
background: url(//www.google.com/images/example);
}Всегда используйте для отступа четыре пробела.
Не используйте табуляцию и не смешивайте табуляцию с пробелами.
<ul>
<li>Fantastic
<li>Great
</ul>Всегда пишите в нижнем регистре.
Весь код должен быть написан в нижнем регистре: это относится к названиям HTML элементов, атрибутов, значениям атрибутов (кроме CDATA), CSS селекторам, свойствам и их значениям (кроме строковых).
<!-- плохо -->
<A HREF="/">Home</A>
<!-- хорошо -->
<img src="google.png" alt="Google">
/* плохо */
color: #E5E5E5;
/* хорошо */
color: #e5e5e5;Удаляйте пробелы в конце строки.
Пробелы в конце строк не обязательны и усложняют использование diff.
<!-- плохо -->
<p>What?_
<!-- хорошо -->
<p>Yes please.###Кодировка Используйте UTF-8 (без BOM)
Убедитесь, что ваш редактор использует кодировку UTF-8 без метки порядка байтов (BOM).
Указывайте кодировку в HTML шаблонах и документах с помощью <meta charset="utf-8">. Не указывайте кодировку для сss-файлов: для них UTF-8 задана по умолчанию.
(Больше о кодировках и о том, как их использовать: Handling character encodings in HTML and CSS.)
###Комментарии По возможности поясняйте свой код, где это необходимо.
Используйте комментарии, чтобы пояснить свой код: что он делает, за что отвечает, и почему используется выбранное решение.
(Этот пункт не обязателен, потому что нет смысла ожидать, что код всегда будет полностью задокументирован. Польза комментирования зависит от сложности проекта и может различаться для HTML и CSS кода.)
###Задачи Отмечайте задачи для списка дел с помощью TODO.
Отмечайте задачи с помощью ключевого слова TODO. Не используйте другие часто встречающиеся форматы, такие как @@.
Заключайте контакты (имя пользователя или список адресатов) в круглые скобки: TODO(контакт).
Описывайте задачу после двоеточия, например: TODO: Задача.
{# TODO(john.doe): revisit centering #}
<center>Test</center>
<!-- TODO: remove optional tags -->
<ul>
<li>Apples</li>
<li>Oranges</li>
</ul>Используйте HTML5.
HTML5 (HTML синтаксис) рекомендуется для всех HTML документов: <!DOCTYPE html>.
(Рекомендуется использовать HTML с типом контента text/html. Не используйте XHTML, так как application/xhtml+xml хуже поддерживается браузерами и ограничивает возможность оптимизации.)
Не закрывайте самозакрывающиеся тэги, например, пишите <br>, вместо <br />.
###Валидность HTML По возможности используйте валидный HTML.
Используйте валидный HTML код, кроме случаев, когда использование не позволяет достичь размера файла, необходимого для нужного уровня производительности.
Используйте такие инструменты как W3C HTML validator чтобы проверить валидность кода.
Валидность — это важное и при этом измеряемое качество кода. Для написания валидного HTML требуется изучение технических требований и ограничений, что обеспечивает правильное использование HTML.
<!-- плохо -->
<title>Test</title>
<article>This is only a test.
<!-- хорошо -->
<!DOCTYPE html>
<meta charset="utf-8">
<title>Test</title>
<article>This is only a test.</article>Используйте HTML так, как он был задуман.
Используйте элементы (иногда неверно называемые “тегами”) по назначению: заголовки для заголовков, p для абзацев, a для ссылок и т.д.
Это облегчает чтение, редактирование и поддержку кода.
<!-- плохо -->
<div onclick="goToRecommendations();">All recommendations</div>
<!-- хорошо -->
<a href="recommendations/">All recommendations</a>Всегда указывайте альтернативное содержимое для мультимедиа.
Постарайтесь указать альтернативное содержимое для мультимедиа: например для картинок, видео или анимаций, заданных с помощью canvas. Для картинок это осмысленный альтернативный текст (alt), а для видео и аудио - расшифровки текста и подписи, если это возможно.
Альтернативное содержимое может помочь людям с ограниченными возможностями. Например, человеку со слабым зрением сложно понять, что на картинке если для нее не задан @alt. Другим людям может быть тяжело понять о чем говорится в видео или аудио записи.
(Если для картинки alt избыточен, или она используется только в декоративных целях в местах, где нельзя использовать CSS, используйте пустой альтернативный текст alt="".)
<!-- плохо -->
<img src="spreadsheet.png">
<!-- хорошо -->
<img src="spreadsheet.png" alt="Spreadsheet screenshot.">Разделяйте структуру, оформление и поведение.
Держите структуру (разметка), оформление (стили) и поведение (скрипты) раздельно и постарайтесь свести взаимодействие между ними к минимуму.
Убедитесь, что документы и шаблоны содержат только HTML, и что HTML служит только для задания структуры документа. Весь код, отвечающий за оформление, перенесите в файлы стилей, а код отвечающий за поведение — в скрипты.
Старайтесь сократить их пересечения к минимуму, включая в шаблоны минимальное количество файлов стилей и скриптов.
Отделение структуры от представления и поведения помогает облегчить поддержку кода. Изменение шаблонов и HTML-документов всегда занимает больше времени чем изменение файлов стилей или скриптов.
<!-- плохо -->
<!DOCTYPE html>
<title>HTML sucks</title>
<link rel="stylesheet" href="base.css" media="screen">
<link rel="stylesheet" href="grid.css" media="screen">
<link rel="stylesheet" href="print.css" media="print">
<h1 style="font-size: 1em;">HTML sucks</h1>
<p>I’ve read about this on a few sites but now I’m sure:
<u>HTML is stupid!!1</u>
<center>I can’t believe there’s no way to control the styling of
my website without doing everything all over again!</center>
<!-- хорошо -->
<!DOCTYPE html>
<title>My first CSS-only redesign</title>
<link rel="stylesheet" href="default.css">
<h1>My first CSS-only redesign</h1>
<p>I’ve read about this on a few sites but today I’m actually
doing it: separating concerns and avoiding anything in the HTML of
my website that is presentational.
<p>It’s awesome!Не используйте ссылки-мнемоники.
Нет смысла использовать ссылки-мнемоники, такие как —, ”, или ☺, когда все разработчики в команде используют одну кодировку (UTF-8).
Единственное исключение из этого правила — служебные символы HTML (например < и &), а так же вспомогательные и “невидимые” символы (например неразрывный пробел).
<!-- плохо -->
The currency symbol for the Euro is “&eur;”.
<!-- хорошо -->
The currency symbol for the Euro is “€”.###Необязательные теги Не используйте необязательные теги. (не обязательно)
Для уменьшения размера файлов и лучшей читаемости кода можно опускать необязательные теги. В HTML5 specification есть список необязательных тегов.
(Может потребоваться некоторое время для того, чтобы этот подход начал использоваться повсеместно, потому что это сильно отличается от того, чему обычно учат веб-разработчиков. С точки зрения согласованности и простоты кода лучше всего опускать все необязательные теги, а не некоторые из них.)
<!-- плохо -->
<!DOCTYPE html>
<html>
<head>
<title>Spending money, spending bytes</title>
</head>
<body>
<p>Sic.</p>
</body>
</html>
<!-- хорошо -->
<!DOCTYPE html>
<title>Saving money, saving bytes</title>
<p>Qed.Не указывайте атрибут type при подключении стилей и скриптов.
Не используйте атрибут type при подключении стилей (кроме вариантов когда используется что-то кроме CSS) и скриптов (кроме вариантов когда это не JavaScript).
Указывать атрибут type в данном случае не обязательно потому что HTML5 использует text/css и text/javascript по умолчанию. Это будет работать даже в старых браузерах.
Type следует указывать только когда тэг script используется для хранения шаблона(type="text/template")
<!-- плохо -->
<link rel="stylesheet" href="//www.google.com/css/maia.css" type="text/css">
<!-- хорошо -->
<link rel="stylesheet" href="//www.google.com/css/maia.css">
<!-- плохо -->
<script src="//www.google.com/js/gweb/analytics/autotrack.js" type="text/javascript"></script>
<!-- хорошо -->
<script src="//www.google.com/js/gweb/analytics/autotrack.js"></script>Выделяйте новую строку для каждого блочного, списочного или табличного элемента и ставьте отступы для каждого дочернего элемента.
Независимо от стилей, заданных для элемента (CSS позволяет изменить поведение элемента с помощью свойства display), переносите каждый блочный или табличный элемент на новую строку.
Также ставьте отступы для всех элементов вложенных в блочный, списочный или табличный элемент.
(Если у вас возникнут сложности из-за пробельных символов между списочными элементами, допускается поместить все li элементы в одну строку. Для Lint рекомендуется в данном случае выдавать предупреждение вместо ошибки.)
<blockquote>
<p><em>Space</em>, the final frontier.</p>
</blockquote>
<ul>
<li>Moe
<li>Larry
<li>Curly
</ul>
<table>
<thead>
<tr>
<th scope="col">Income
<th scope="col">Taxes
<tbody>
<tr>
<td>$ 5.00
<td>$ 4.50
</table>###Заключение в кавычки Используйте двойные кавычки для значений атрибутов.
Используйте двойные кавычки ("") вместо одинарных ('') для значений атрибутов.
<!-- плохо -->
<a class='maia-button maia-button-secondary'>Sign in</a>
<!-- хорошо -->
<a class="maia-button maia-button-secondary">Sign in</a>