"Каждая линия кода должна быть написана так, будто её писал лишь один человек, вне зависимости от количества разработчиков." - Китайская народная пословица.
Этот документ описывает правила написания кода для языков, которые я использую: HTML, CSS и Javascript.
Этот репозиторий не был задуман как целый проект для описания моего стиля кода. Я лишь хотел поместить её сюда для себя и для других разработчиков, участвующих в моих проектах, чтобы информировать их о стандартах, которые я использую.
Так как это новый документ, некоторые участки кода в старых проектах могут не соответствовать данным правилам.
Этот документ постоянно обновляется и время от времени могут появляться изменения
Для облегчения содействия других людей в проектах, все описания commit'ов, названия pull request'ов или записей о багах должны быть написаны на Английском языке
Прежде чем commit'ить что-либо, нужно проверять, нет ли других commit'ов с таким названием. Если такие есть, писать номер исправления после символа #
// Правильно
git commit -m "Add placeholder in input #10"
// Неправильно
git commit -m "Add placeholder in input"Основы раздела про HTML взяты с "Code Guide by @mdo".
- Синтаксис HTML
- Комментарии HTML
- Кодировка документов HTML
- Порядок аттрибутов в HTML
- Производительность HTML-кода
- Базовый шаблон HTML-кода
Используйте мягкую табуляцию (soft tabs) размером в два пробела. Это настраивается в редакторе кода.
<!-- Правильно -->
<nav class="nav">
<ul class="nav-menu">
<li class="nav-item">
<a class="nav-link">
<!-- Неправильно -->
<nav class="nav">
<ul class="nav-menu">
<li class="nav-item">
<a class="nav-link">Всегда используйте двойные кавычки в HTML.
<!-- Правильно -->
<div class="main">
<!-- Неправильно -->
<div class='main'>Не включайте символ '/' в самозакрывающиеся теги.
<!-- Правильно -->
<hr>
<!-- Неправильно -->
<hr />Разделяйте блочные элементы пустой строкой и группируйте внутренние элементы блоков
<!-- Правильно -->
<ul class="nav-tabs">
<li>...</li>
<li>...</li>
<li>...</li>
<li>...</li>
</ul>
<div class="tab-content">
...
</div>
<!-- Неправильно -->
<ul class="nav-tabs">
<li>...</li>
<li>...</li>
<li>...</li>
<li>...</li>
</ul>
<div class="tab-content">
...
</div>Следуйте этому правилу при написании комментариев:
<!-- Пример комментариев в HTML -->
<!-- /Конец примера комментариев в HTML -->Всегда используйте кодировку UTF-8 в документах.
<head>
<meta charset="UTF-8">
</head>Атрибуты в HTML должны следовать данному порядку для облегчения чтения кода.
classid,namedata-*src,for,type,hreftitle,altaria-*,role
<a class="..." id="..." data-modal="toggle" href="#">
<input class="form-control" type="text">
<img class="img-rounded" src="..." alt="...">Нет необходимости указывать тип CSS и JS файлов в атрибуте type, такие как text/css и text/javascript.
<!-- Правильно -->
<link rel="stylesheet" href="assets/css/style.css" />
<script src="scripts.min.js"></script>
<!-- Не правильно -->
<script src="scripts.min.js"></script>
</head>
<body>Для увеличения скорости загрузки страницы указывайте ссылки на Javascript-скрипты перед закрывающим тегом <body>.
<!-- Правильно -->
<script src="scripts.min.js"></script>
</body>
<!-- Не правильно -->
<script src="scripts.min.js"></script>
</head>
<body>Всегда сокращайте код в проектах на чистом HTML. Таск-менеджеры, вроде Gulp упрощают эту задачу.
<!-- Правильно -->
<html><head>...</head><body><div class="container">...</div></body></html>
<!-- Неправильно -->
<html>
<head>
...
</head>
<body>
<div class="container">
...
</div>
</body>
</html>Этот код следует использовать для быстрого начала работы над новым проектом:
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="format-detection" content="telephone=no">
<meta name="viewport" content="width=device-width">
<link rel="shortcut icon" href="assets/img/ico/favicon.ico" />
<link rel="logo" type="image/svg" href="../assets/img/logo/logo.svg" />
<link rel="stylesheet" href="assets/css/style.css" />
<title></title>
</head>
<body>
<!-- Скрипты -->
<script src="assets/js/scripts.min.js"></script>
</body>
</html>Немного совместимости с IE...
<!DOCTYPE html>
<!--[if IE]><![endif]-->
<!--[if IE 7 ]> <html lang="en" class="ie7"> <![endif]-->
<!--[if IE 8 ]> <html lang="en" class="ie8"> <![endif]-->
<!--[if IE 9 ]> <html lang="en" class="ie9"> <![endif]-->
<!--[if (gt IE 9)|!(IE)]><!--><html lang="en"><!--<![endif]-->
<head>
...Сейчас я (автор) использую Jade как шаблонизатор.
Аналогично с HTML, используйте мягкие табы размером в два пробела. Настраивается в вашем редакторе.
//- Правильно
nav.navbar
ul.nav
li.nav-item
a.nav-link
//- Неправильно
nav.navbar
ul.nav
li.nav-item
a.nav-linkВсегда используйте одинарные кавычки.
//- Правильно
button.btn(data-toggle='collapse')
//- Неправильно
button.btn(data-toggle="collapse")Напишите заголовок блока, разделяйте блочные элементы двумя чистыми линиями и группируйте внутренние элементы блока.
//- Правильно
//- Header
//- ===================================
header.header(role='banner')
a.logo(href='#', role='logo')
//- Main
//- ===================================
main.main(role='main')
section.content
//- Неправильно
header.header(role='banner')
a.logo(href='#', role='logo')
main.main(role='main')
section.contentПри добавлении комментариев следуйте этому правилу
//- Это пример правильного комментария
// А это пример неправильногоКомментарии с //- в начале не компилируются в HTML.
Код далее помогает быстро стартовать проект
doctype html
html(lang='en')
head
meta(charset='utf-8')
meta(name='description', content='')
meta(name='viewport', content='width=device-width, initial-scale=1')
meta(name='format-detection', content='telephone=no')
//- Title
//- ===================================
title Заголовок страницы
//- Favicon and SVG logo
//- ===================================
link(rel='shortcut icon', href='ico/favicon.ico')
link(rel='logo', type='image/svg', href='svg/logo/logo.svg')
//- Stylesheet and fonts
//- ===================================
link(href='css/style.css', rel='stylesheet')
body
//- Scripts
//- ===================================
script(src='js/scripts.min.js') Основы раздела про CSS взяты с Code Guide by @mdo и "Разговорный CSS".
- Синтаксис CSS
- Порядок обьявления в CSS
- Имена классов в CSS
- Производительность CSS
- Адаптивность и @media-запросы
Используйте мягкую табуляцию размером в два символа пробела. Это настраивается в редакторе кода.
/* Правильно */
.nav-item {
display: inline-block;
margin: 0 5px;
}
/* Неправильно */
.nav-item {
display: inline-block;
margin: 0 5px;
}Всегда используйте двойные кавычки.
/* Правильно */
[type="text"]
[class^="..."]
.nav-item:after {
content: "";
}
/* Неправильно */
[type='text']
[class^='...']
.nav-item:after {
content: '';
}Всегда вставляйте один пробел перед символом фигурной скобки
/* Правильно */
.header {
...
}
/* Неправильно */
.header{
...
}После двоеточия объявления свойства также вставляйте один пробел
/* Правильно */
.header {
margin-bottom: 20px;
}
/* Неправильно */
.header{
margin-bottom:20px;
}В блоке объявлений свойств после каждого свойства всегда вставляйте точку с запятой
/* Правильно */
.header {
margin-bottom: 20px;
}
/* Неправильно */
.header{
margin-bottom:20px
}Каждый селектор при его объявлении пишите на отдельной строке
/* Правильно */
.selector-1,
.selector-2,
.selector-3 {
...
}
/* Неправильно */
.selector-1, .selector-2, .selector-3 {
...
}Обьявления селекторов с единственным свойством пишите вместе со свойством на одной строке
/* Правильно */
.selector-1 { width: 50%; }
/* Неправильно */
.selector-1 {
width: 50%;
}Разделяйте каждое объявление селектора пустой строкой.
/* Правильно */
.selector-1 {
...
}
.selector-2 {
...
}
/* Неправильно */
.selector-1 {
...
}
.selector-2 {
...
}Используйте нижний регистр и сокращения для обозначения шестнадцетиричных цветов
Не пишите обозначений для нулевых величин.
/* Правильно */
.selector-1 {
color: #aaa;
margin: 0;
}
/* Неправильно */
.selector-1 {
color: #AAAAAA;
margin: 0px;
}Объявления свойств должны идти в алфавитном порядке
/* Правильно */
.selector-1 {
background: #fff;
border: #333 solid 1px;
color: #333;
display: block;
height: 200px;
margin: 5px;
padding: 5px;
width: 200px;
}
/* Неправильно */
.selector-1 {
padding: 5px;
height: 200px;
background: #fff;
margin: 5px;
width: 200px;
color: #333;
border: #333 solid 1px;
display: block;
}Используйте только нижний регистр и вставляйте дефисы между словами
/* Правильно */
.nav-item { ... }
/* Неправильно */
.NavItem { ... }
.nav_item { ... }Дефисы также необходимы для того, чтобы показать принадлежность одного селектора к другому. Префиксами можно подписывать селекторы родителей для удобного чтения кода.
/* Правильно */
.navbar { ... }
.nav { ... }
.nav-item { ... }
.nav-link { ... }
/* Неправильно */
.item-nav { ... }
.link-nav { ... }Избегайте слишком коротких имён селекторов и всегда выбирайте пододящие по смыслу имена
/* Правильно */
.btn { ... }
.page-header { ... }
.progress-bar { ... }
/* Неправильно */
.s { ... }
.ph { ... }
.block { ... }Никогда не используйте идентификаторы.
/* Правильно */
.header { ... }
.section { ... }
/* Неправильно */
#header { ... }
#section { ... }Всегда отдавайте предпочтения классам, а не названиям тегов или другим стандартным селекторам
/* Правильно */
.form-control { ... }
.header { ... }
.section { ... }
/* Неправильно */
input[type="text"] { ... }
header
sectionИзбегайте вложенных элементов, используйте вместо них отдельные классы
/* Правильно */
.navbar { ... }
.nav { ... }
.nav-item { ... }
.nav-link { ... }
/* Неправильно */
.navbar ul { ... }
.navbar ul li { ... }
.navbar ul li a { ... }Используйте селекторы со вложенностью только когда нужно поменять свойства класса в зависимости от его вложенности в другие классы. Не углубляйтесь дальше трёх селекторов
/* Правильно */
.modal-footer .btn { ... }
.progress.active .progress-bar { ... }
/* Неправильно */
.modal-btn { ... }
.progress.active .progress-bar .progress-item span { ... }Сокращайте CSS-код. Таск-менеджеры, такие как Gulp упрощают это.
/* Правильно */
.navbar { ... }.nav { ... }.nav-item { ... }.nav-link { ... }
/* Неправильно */
.nav-item {
...
}
.nav-link {
...
}Начинайте разработку с введения основных правил и @media-запросов для разработки с паттерном mobile-first.
/* Правильно */
.navbar {
margin-bottom: 20px;
}
@media (min-width: 480px) {
.navbar {
padding: 10px;
}
}
@media (min-width: 768px) {
.navbar {
position: absolute;
top: 0;
left: 0;
}
}
@media (min-width: 992px) {
.navbar {
position: fixed;
}
}
/* Неправильно */
.navbar {
position: fixed;
top: 0;
left: 0;
}
@media (max-width: 767px) {
.navbar {
position: static;
padding: 10px;
}
}Держите @media-запросы как можно ближе к тому правилу, к которому они относятся. Не выделяйте их в отдельную таблицу стилей или в конец документа
.navbar { ... }
.nav { ... }
.nav-item { ... }
@media (min-width: 480px) {
.navbar { ... }
.nav { ... }
.nav-item { ... }
}Во всех своих проектах я (автор) использую препроцессоры. Сейчас я перешёл на Stylus, но в некоторых проектах ещё используется LESS.
- Синтаксис CSS-препроцессоров
- Производительность CSS-препроцессоров
- Медиазапросы в препроцессорах
- Комментарии в CSS-препроцессорах
Используйте мягкую табуляцию размером в два символа пробела. Это настраивается в редакторе кода.
// Правильно
.nav-item
display inline-block
// Неправильно
.nav-item
display inline-block Не используйте символы ";", ":" и фигурные скобки
// Правильно
.header
position fixed
top 0
right 0
left 0
// Неправильно
.header {
position: fixed;
top: 0;
right: 0;
left: 0;
}Каждый селектор объявляйте на отдельной строке.
// Правильно
.selector-1,
.selector-2,
.selector-3
...
// Неправильно
.selector-1, .selector-2, .selector-3
... Разделяйте вложенные правила пустыми строками, а блоки разделяйте двумя пустыми строками.
// Правильно
.navbar
margin 0 0 20px
li
display inline-block
.nav
display block
li
float left
// Неправильно
.navbar
margin 0 0 20px
li
display inline-block
.nav
display block
li
float leftИспользуйте $ для переменных.
// Правильно
$gray-darker = #111
$gray-dark = #393C45
$gray = #555
$gray-light = #aaa
$gray-lighter = #ECF1F5
$gray-white = #fbfbfbДержитесь подальше от вложенностей, как и в чистом CSS
// Правильно
.nav-item
...
// Неправильно
.navbar
.nav
.nav-item
... Не используйте @extend'ы, Всегда пользуйтесь миксинами.
reset(arg = '')
if (arg == list)
margin 0
padding-left 0
list-style none
if (arg == form)
background 0
border 0
padding 0
.nav
reset(list)
.btn
reset(form)Пишите медиазапросы для элементов прямо внутри них
.navbar
position absolute
top 5px
z-index 5
@media (min-width $screen-sm)
position fixed
margin-right $space-sm
@media (min-width $screen-md)
right 0
top 10px Предоставляйте оглавление в начале каждого файла.
//
// Variables
//
// 1. Colors
// 2. Spaces
// 3. Media Queries
// 4. Typography
//
// ===============================================================
//
// 1. Colors
// --------------------------------------------------
...
//
// 2. Spaces
// --------------------------------------------------
...Для главных элементов
//
// 1. Header
// --------------------------------------------------
... Для подэлементов
// 1.1 Header Item
// --------------------------------------------------
...Обычные комментарии
// Простой комментарий
// Блочный
// комментарий
...Основой этой части документа стали: "idiomatic.js" и "Zeno Rocha Coding Style".
- Синтаксис Javascript
- Переменные Javascript
- Производительность Javascript-кода
- JS и data-атрибуты HTML5
- Комментарии в Javascript
Используйте мягкую табуляцию размером в два символа пробела. Это настраивается в редакторе кода.
// Правильно
while (condition) {
statements
}
// Неправильно
while (condition) {
statements
}Всегда прописывайте точку с запятой в конце строки.
// Правильно
var me = $(this);
test();
// Неправильно
var me = $(this)
test()Всегда используйте одинарные кавычки
// Правильно
var string = '<p class="foo">Lorem Ipsum</p>';
var noteClick = me.attr('data-note');
// Неправильно
var string = "<p class='foo'>Lorem Ipsum</p>";
var noteClick = me.attr("data-note");Пишите else на той же строке, что и закрывающая фигурная скобка блока инструкций выражения if.
// Правильно
if ( true ) {
...
} else {
...
}
// Неправильно
if ( true ) {
...
}
else {
...
}Добавляйте пробелы между операторами.
// Правильно
for (i = 0; i < 10; i++) {
...
}
// Неправильно
for (i=0;i<10;i++) {
...
}Никогда не добавляйте пробелов после названия функции и перед её первым аргументом.
// Правильно
foo(function() {
...
});
// Неправильно
foo ( function () {
...
});Добавляйте пробелы за пределами круглых скобок, но избегайте пробелов внутри.
// Правильно
if (condition) {
statement
}
// Неправильно
if( condition ){
statement
}Для условных операторов if/else/else if всегда использовать фигурные скобки {}.
// Правильно
if (condition) {
statement
} else if (condition) {
statement
} else {
statement
}
// Неправильно
if (condition) statement;
else if (condition) statement;
else statement;Проверка значений на равенство чаще всего должна быть строгой (===), нестрогую (==) использовать только в крайних случаях.
// Правильно
if (foo === 'foo') {
statement
}
// Неправильно
if (foo == 'foo') {
statement
}Все переменные перед использованием должны быть объявлены.
// Правильно
var me = $(this);
var noteClick = me.attr('data-note');
notes[noteClick].play();
// Неправильно
notes[noteClick].play();
var me = $(this);
var noteClick = me.attr('data-note');Всегда используйте var для объявления переменных.
// Правильно
var me = $(this);
// Неправильно
me = $(this);Используйте JSHint для выявления ошибок и проблем кода.
Всегда сокращайте и конкатенируйте весь Javascipt-код. Таск-менеджеры, такие как Grunt упрощают этот процесс.
Избегайте использования классов в javascript-манипуляциях. Лучше используйте Data-атрибуты HTML5.
// Правильно
$('[data-toggle="tab"]');
// Неправильно
$('.tab');Такой подход оставляет на классах всё, что связано со стилями. Потому что некоторые элементы, стилизованные одинаково могут по-разному функционировать.
Комментарий должен идти одной строкой над строкой комментируемого кода
// Правильно
// Пример хорошего комментария
var me = $(this);
// Неправильно
var me = $(this); // Пример плохого комментарияЯ (автор) сделал стартовый шаблон для этого code style.
Он называется Kratos Boilerplate.
MIT License © Luiz Felipe Tartarotti Fialho