Разработчику > Соглашение по оформлению кода на javascript > Общий стиль

За основу взяты правила jquery и google с учетом интеграции с ESLint в Microsoft Visual Studio (макс. размер файла 35 кБ).

1. В начало скрипта необходимо добавить блочный комментарий «globals» с описанием используемых глобальных переменных в формате инструкций ESLint.
Пример:

/* globals X:true, Y, fsShell, F:true */

После названия переменной можно указать разрешение на перезапись переменной: true - переменная может быть переопределена, false - переменная только для чтения.
2. После инструкций ESLint необходимо добавить блочный комментарий с общим описанием скрипта, включающий: наименование продукта, имени файла, его предназначения и требуемые для его работы другие скрипты.
Пример:

/*
    Finist-Soft(c) WebPlatform.
    Файл "/index.js": скрипты страницы "/index.html".
    Требует: helper.js. -- список необходимых доп. скриптов.
*/

3. Располагайте функции под кодом, который их использует. Т.е. вызов функции должен быть описан до определения самой функции.
4. Для обозначения текстовых строк используются преимущественно одинарные кавычки. Как дополнительные (внутри одинарных кавычек) разрешены двойные кавычки и апострофы. В апострофах текст разрешен, только если используется конструкция формирования текста по шаблону (ESLint).
5. Разбивка текста:
   1. Максимальная длина строки 120 символов, за исключением случаев, когда строка содержит URL или Regex литерал, которые завершают строку (ESLint).
   2. Длинные текстовые строки разделяются оператором конкатенацией строк в конце строки (ESLint).
   Пример:

   stroka = 'Это очень длинная строка' +
           ', разбитая на части';

   3. В качестве отступов необходимо использовать группу из 4 пробелов (ESLint).
   4. Строки не должны завершатся на пробел. В том числе в коде не должно быть строк, состоящих из одних пробелов (ESLint).
   5. В конце скрипта должна быть пустая строка (ESLint).
   6. Запрещены пробелы перед знаками: “,” и “;” (ESLint).
   7. Следует избегать длинных вертикальных блоков кода без разрыва пустой строкой или комментарием. Исключение, когда строки кода имеют одинаковые смысл и конструкцию.
   8. Запрещено использование более двух пустых строк подряд (ESLint).
   9. Рекомендуется после каждого закрытого блока ставить пустую строку.
   10. Запрещены пробелы в пустых конструкциях (“{}”, “()”, “[]” и др.) (ESLint).
   11. Если цепочка вызовов свойств объектов не умещается на одной строке, то каждый вызов оформлять на отдельной строке. При этом точка ставится в начале строки перед свойством объекта (ESLint).
   Пример:

   // Разбивка свойств объекта на строки
       stroka = fsShell
           .support
           .superPuperLib
           .calcS();
   

   12. Условные операторы («==», «===», «>» и др.) обрамляются пробелами (ESLint).
   13. Унарные операторы над переменной («!», «++» и т.д.) не должны отделяться пробелом от переменной (ESLint).
   14. В декларации объекта пробел указывается только после символа «:»(ESLint).
6. Комментарии:
   1. Комментарии могут быть блочными, однострочными и в конце строки.
   2. Комментарии внутри строки кода запрещены.
   3. Перед комментарием должна идти пустая строка, за исключением начала файла, начала декларации объекта или массива, и комментария в конце строки.
   4. Между текстом комментария и конструкцией, определяющей начало комментария должен быть один пробел.
   5. Текст комментария следует начинать с прописной буквы. (ESLint).
   6. Все функции должны сопровождаться блочным комментарием документации в стиле JSDoc (блочные комментарии начинаются на «/**», см. приложение 1) (ESLint).
   7. Рекомендуется внутри функций использовать только однострочные комментарии, даже если строк несколько.
   8. В комментариях допускается использование выражений «TODO:», «FIXME» и «XXX» для отметки их в списке предупреждений при сборке проекта.
7. Следует минимизировать использование круглых скобок, за исключением обертывания в скобки регулярного выражения (ESLint).
8. Условные операторы:
   1. В кратких условиях, если условие сложное, то для повышения читабельности блоки действий переносятся на отдельные строки, а при необходимости на отдельные строки разбивается и само условие. При этом операторы “?” и “:” ставятся в конце строки (ESLint).
   2. В кратких условиях пробелы ставятся вокруг “?” и “:” (ESLint).
   3. В полных условиях сложные длинные условия должны разбиваться на несколько строк для повышения читабельности.
   4. При возможности использовать более простые формы сочетаний нескольких условий (ESLint).
   5. В многострочных условных выражениях логические операторы (And, Or) ставятся в конце строки (ESLint).
9. Для файлов допускается наименование в нижнем регистре, слова через подчеркивание.
10. Рекомендуется максимальное использование стандартизированных возможностей, вместо специфичных возможностей (для повышения переносимости кода).
11. Для проектов, у которых подключено тестирование JS, в начале скрипта после инструкции ESLint вставлять определение пустой функции testCompile для проверки корректной компиляции срипта. Соотвественно когда появилась необходимость выделения теста компиляции – нужно сделать тест в отдельном блоке describe (группа тестов) с именем «JS: тесты компиляции: », а внутри один блок it(тест) с именем тестируемого скрипта. А внутри теста вызвать объявленнную ранее функцию с «try… catch…».