Стиль кода от LFeh

"Каждая линия кода должна быть написана так, будто её писал лишь один человек, вне зависимости от количества разработчиков." - Китайская народная пословица.

Этот документ описывает правила написания кода для языков, которые я использую: HTML, CSS и Javascript.

Этот репозиторий не был задуман как целый проект для описания моего стиля кода. Я лишь хотел поместить её сюда для себя и для других разработчиков, участвующих в моих проектах, чтобы информировать их о стандартах, которые я использую.

Так как это новый документ, некоторые участки кода в старых проектах могут не соответствовать данным правилам.

Этот документ постоянно обновляется и время от времени могут появляться изменения

Содержание

[Git] (#commits)
[HTML] (#html)
[CSS] (#css)
[Javascript] (#js)
Ссылки
Переводы
Лицензия

1. Git

Для облегчения содействия других людей в проектах, все описания commit'ов, названия pull request'ов или записей о багах должны быть написаны на Английском языке

Прежде чем commit'ить что-либо, нужно проверять, нет ли других commit'ов с таким названием. Если такие есть, писать номер исправления после символа #

// Правильно
git commit -m "Add placeholder in input #10"

// Неправильно
git commit -m "Add placeholder in input"

2. HTML

Основы раздела про HTML взяты с "Code Guide by @mdo".

Оглавление HTML

[Синтаксис HTML] (#html-syntax)
[Комментарии HTML] (#html-comments)
[Кодировка документов HTML] (#html-encoding)
[Порядок аттрибутов в HTML] (#html-attribute-order)
[Производительность HTML-кода] (#html-performance)
[Базовый шаблон HTML-кода] (#html-base)

2.1. Синтаксис HTML

Используйте мягкую табуляцию размером в два символа пробела. Это настраивается в редакторе кода.

<!-- Правильно -->
<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>

2.2. Комментарии в HTML

Следуйте этому правилу при написании комментариев:

<!-- Пример комментариев в HTML -->
<!-- /Конец примера комментариев в HTML -->

2.3. Кодировка HTML-документво

Всегда используйте кодировку UTF-8 в документах.

<head>
  <meta charset="UTF-8">
</head>

2.4. Порядок аттрибутов в HTML

Аттрибуты в HTML должны следовать данному порядку для облегчения чтения кода.

class
id, name
data-*
src, for, type, href
title, alt
aria-*, role

<a class="..." id="..." data-modal="toggle" href="#">

<input class="form-control" type="text">

<img class="img-rounded" src="..." alt="...">

2.5. Производительность HTML

Нет необходимости указывать тип 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. Таск-менеджеры, вроде Grunt leaves this easier.

<!-- Good -->
<html><head>...</head><body><div class="container">...</div></body></html>

<!-- Bad -->
<html>
  <head>
    ...
  </head>
  <body>
    <div class="container">
      ...
    </div>
  </body>
</html>

2.6. Базовый шаблон 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>
...

3. CSS

Основы раздела про CSS взяты с Code Guide by @mdo и "Разговорный CSS".

Оглавление CSS

[Синтаксис CSS] (#css-syntax)
[Порядок обьявления в CSS] (#css-order)
[Имена классов в CSS] (#css-class-name)
[Производительность CSS] (#css-performance)
[Адаптивность и @media-запросы] (#mobile-first-and-media-queries)
[Препроцессоры] (#css-pre-processors)
[Комментарии в CSS] (#css-comments)

3.1. Синтаксис

Используйте мягкую табуляцию размером в два символа пробела. Это настраивается в редакторе кода.

/* Правильно */
.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;
}

3.2. Порядок объявлений в CSS

Объявления свойств должны идти в алфавитном порядке

/* Правильно */
.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;
}

3.3. Имена классов в CSS

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

/* Правильно */
.nav-item { ... }

/* Неправильно */
.NavItem { ... }
.nav_item { ... }

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

/* Правильно */
.navbar { ... }
.nav { ... }
.nav-item { ... }
.nav-link { ... }

/* Неправильно */
.item-nav { ... }
.link-nav { ... }

Избегайте слишком коротких имён селекторов и всегда выбирайте пододящие по смыслу имена

/* Правильно */
.btn { ... }
.page-header { ... }
.progress-bar { ... }

/* Неправильно */
.s { ... }
.ph { ... }
.block { ... }

3.4. Производительность CSS

Никогда не используйте идентификаторы.

/* Правильно */
.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-код. Таск-менеджеры, такие как Grunt упрощают это.

/* Правильно */
.navbar { ... }.nav { ... }.nav-item { ... }.nav-link { ... }

/* Неправильно */
.nav-item {
  ...
}
.nav-link {
  ...
}

3.5 Адаптивность и @media-запросы

Начинайте разработку части кода с введения основных правил и @media-запросов для этой части.

/* Правильно */
.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 { ... }
}

3.6. Препроцессоры

Во всех своих проектах я (автор) использую LESS.

Осторожнее с гнездящимися элементами. Лучше просто продолжайте обходиться без них.

/* Правильно */
.nav-item { ... }

/* Неправильно */
.navbar {
  .nav {
    .nav-item {
      ...
    }
  }
}

Имена переменных должны быть семантическими.

/* Правильно */
@brand-primary: #049cdb;

/* Неправильно */
@color-blue: #049cdb;

3.7. Комментарии в CSS

Все комментарии должны быть написаны в синтаксисе используемого препроцессора

//
// Раздел
// --------------------------------------------------

// Подраздел
// --------------------------------------------------

//
// Блок комментариев
//
//

// Простой комментарий

4. Javascript

Основой этой части документа стали: "idiomatic.js" и "Zeno Rocha Coding Style".

Оглавление Javascript

[Синтаксис Javascript] (#js-syntax)
[Переменные Javascript] (#js-variables)
[Производительность Javascript-кода] (#js-performance)
[Комментарии в Javascript] (#js-comments)

4.1. Синтаксис 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
}

4.2. Переменные Javascript

Все переменные перед использованием должны быть объявлены.

// Правильно
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);

4.3. Производительность Javascript-кода

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

Всегда сокращайте и конкатенируйте весь Javascipt-код. Таск-менеджеры, такие как Grunt упрощают этот процесс.

4.4. Комментарии Javascript

Комментарий должен идти одной строкой над строкой комментируемого кода

// Правильно
// Пример хорошего комментария
var me = $(this);

// Неправильно
var me = $(this); // Пример плохого комментария

azarro / coding-style

Стиль кода от LFeh

Содержание

1. Git

2. HTML

Оглавление HTML

2.1. Синтаксис HTML

2.2. Комментарии в HTML

2.3. Кодировка HTML-документво

2.4. Порядок аттрибутов в HTML

2.5. Производительность HTML

2.6. Базовый шаблон HTML-документа

3. CSS

Оглавление CSS

3.1. Синтаксис

3.2. Порядок объявлений в CSS

3.3. Имена классов в CSS

3.4. Производительность CSS

3.5 Адаптивность и @media-запросы

3.6. Препроцессоры

3.7. Комментарии в CSS

4. Javascript

Оглавление Javascript

4.1. Синтаксис Javascript

4.2. Переменные Javascript

4.3. Производительность Javascript-кода

4.4. Комментарии Javascript

5. Ссылки

6. Переводы

7. Лицензия

About