Руководство по стилю кодирования JavaScript

внешний интерфейс JavaScript спецификация кода ESLint

впервые опубликовано вличный блог

предисловие

Руководство по стилю написания кода для языка программирования очень важно для долговременно поддерживаемого программного обеспечения; хороший стиль программирования помогает писать более качественные, менее глючные и простые в обслуживании программы.

Работа в команде должна разработать некоторые спецификации кода и использовать некоторые инструменты для обеспечения применения стиля кода команды. В конце концов, людей, которые пишут один код для поддержания кода, так что есть единый код кода !!!

Я смотрел это недавноПишите поддерживаемый JavaScriptа такжеНаписание качественного кода: практика фронтенд-разработки, В соответствии с некоторыми из методов написания, пропагандируемых в книге, и в сочетании с моим личным опытом и предпочтениями, я внес некоторые изменения и примерно разобрал следующие стили кодирования JavaScript.

Стиль кодирования JavaScript

1. Отступ

Уровень каждой строки состоит из 4-х пробелов, избегайте использования табуляции (Tab) для отступа

if (true) {
    doSomething();
}

2. Длина линии

Длина каждой строки не должна превышать 80 символов.Если строка больше 80 символов, она должна переноситься после оператора (запятая, плюс и т.д.) Следующий уровень должен иметь отступ в два уровня (8 символов).

// 好的写法
doSomething(arg1, arg2, arg3, arg4,
        arg5);

// 不好的写法: 第二行只有4个空格的缩进
doSomething(arg1, arg2, arg3, arg4,
    arg5);
// 不好的写法: 在运算符之前换行
doSomething(arg1, arg2, arg3, arg4
        ,arg5);

3. Исходное значение

Следует избегать использования специального значения null, за исключением следующих случаев.

  • Используется для инициализации переменной, которой может быть присвоен объект
  • Используется для сравнения с уже инициализированной переменной, которая может быть или не быть объектом
  • Когда параметр функции ожидает объект, он используется в качестве возвращаемого значения для передачи.
// 好的做法
const person = null;

Чтобы определить, определена ли переменная, следует использовать оператор typeof

// 好的写法
if (typeof constiable == 'undefined') {
    // do something
}

// 不好的写法
if (constiable == 'undefined') {
    // do something
}

4. Расстояние между операторами

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

// 好的写法
const found = (values[i] === item);
// 不好的写法: 丢失了空格
const found = (values[i]===item);

// 好的写法
if (found && (count > 10)) {
    doSomething();
}
// 不好的写法: 丢失了空格
if (found&&(count>10)) {
    doSomething();
}

// 好的写法
for(let i = 0; i < count; i++) {
    process(i);
}
// 不好的写法: 丢失了空格
for(let i=0; i<count; i++) {
    process(i);
}

5. Расстояние между кронштейнами

Когда используются скобки, не должно быть места сразу после открытия скобки и непосредственно перед закрывающим скобками

// 好的写法
const found = (values[i] === item);
// 不好的写法: 左括号之后有额外的空格
const found = ( values[i] === item);

// 好的写法
if (found && (count > 10)) {
    doSomething();
}
// 不好的写法: 右括号之后有额外的空格
if (found && (count > 10) ) {
    doSomething();
}

// 好的写法
for(let i = 0; i < count; i++) {
    process(i);
}
// 不好的写法: 参数两边有额外的空格
for(let i = 0; i< count; i++) {
    process( i );
}

6. Прямой объект

Литералы объектов должны использовать следующий формат

  • Открывающая открывающая фигурная скобка должна находиться на той же строке, что и выражение
  • Пара "имя-значение" для каждого свойства должна иметь отступ на единицу, а первое свойство должно начинаться с новой строки после открывающей фигурной скобки.
  • Пара имя-значение для каждого атрибута должна использовать имя атрибута без кавычек, за которым следует двоеточие (без пробела перед ним), а затем значение
  • Если значением свойства является тип функции, тело функции должно начинаться с новой строки под именем свойства, а до и после него должна быть пустая строка.
  • Пустые строки могут быть вставлены до и после набора связанных свойств для улучшения читаемости кода.
  • Закрытие закрытия вьющихся сковороде должна быть на собственной линейке
// 好的写法
const object = {

    key1: value1,
    key2: value2,

    func: function() {

    },

    key3: value3,
};

// 不好的写法: 不恰当的缩进
const object = {
        key1: value1,
        key2: value2,
    };

// 不好的写法:函数体缺少空行
const object = {

    key1: value1,
    key2: value2,
    func: function() {

    },
    key3: value3,
};

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

// 好的写法
doSomething({
    key1: value1,
    key2: value2,
});

// 不好的写法
doSomething({ key1: value1, key2: value2 });

7. Примечания

Применение комментариев часто помогает другим понять ваш код. Комментарии следует использовать в следующих ситуациях.

  • Код не ясен
  • Может быть ошибочно принят за плохой код
  • Необходимый, но не очевидный код для конкретного браузера
  • Для объектов, методов или свойств необходимо генерировать документацию (с соответствующими комментариями к документации).

1) Однострочный комментарий

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

  • Однострочный комментарий для объяснения следующей строки кода
  • Комментарий в конце строки кода для пояснения предшествующего кода.
  • Несколько строк, используемых для комментирования блока кода
// 好的写法
if (condition) {

    // 如果代码执行到这里,则说明通过了所有的安全性检测
    allowed();
}

// 不好的写法:注释之前没有空行
if (condition) {
    // 如果代码执行到这里,则说明通过了所有的安全性检测
    allowed();
}

// 不好的写法: 错误的缩进
if (condition) {

// 如果代码执行到这里,则说明通过了所有的安全性检测
    allowed();
}

// 不好的写法: 这里应当用多行注释
// 接下来的这段代码非常难, 那么,让我详细的解释一下
// 1. xxxx
// 2. xxxx
if (condition) {

// 如果代码执行到这里,则说明通过了所有的安全性检测
    allowed();
}

В случае однострочных комментариев в конце строки кода убедитесь, что между концом кода и комментарием есть хотя бы один отступ.

// 好的写法
const result = something + somethingElse; // somethingElse will never be null

// 不好的写法: 代码和注释间没有足够的空格
const result = something + somethingElse;// somethingElse will never be null

Использование однострочных комментариев к нескольким последовательным строкам является единственным допустимым случаем при комментировании блока кода. Многострочные комментарии в этом случае использовать не следует.

// 好的写法
// if(condition) {
//     doSomething();
// }

2) Многострочные комментарии

Многострочные комментарии следует использовать, когда для объяснения кода требуется больше текста.Каждый многострочный комментарий должен состоять как минимум из трех следующих строк. 1. Первая строка включает только начало комментария /*, другого текста в этой строке быть не должно. 2. Следующие строки начинаются с * и остаются выровненными по левому краю.Эти строки можно описать текстом 3. Последняя строка начинается с */ и выравнивается с предыдущей строкой, другого текста быть не должно

Первая строка многострочного комментария должна иметь отступ на том же уровне, что и описание кода. Каждая последующая строка должна иметь отступ на том же уровне с добавлением пробела (для правильного выравнивания символов *). многострочный код Пробел должен быть зарезервирован

// 好的写法
if (condition) {

    /*
     * 如果代码执行到这里
     * 说明通过了所有的安全性检测
    */
    allowed();
}

// 不好的写法: 注释之前无空行
if (condition) {
    /*
     * 如果代码执行到这里
     * 说明通过了所有的安全性检测
    */
    allowed();
}
// 不好的写法: 星号后没有空格
if (condition) {

    /*
     *如果代码执行到这里
     *说明通过了所有的安全性检测
    */
    allowed();
}
// 不好的写法: 错误的缩进
if (condition) {

/*
 * 如果代码执行到这里
 * 说明通过了所有的安全性检测
*/
    allowed();
}

// 不好的写法: 代码尾部注释不要用多行注释格式
const result = something + somethingElse; /* somethingElse 不应当取值为null */

3) Заявление об аннотации

Комментарии иногда могут использоваться для объявления дополнительной информации к фрагменту кода. Формат этих объявлений начинается с одного слова, за которым следует двойная кавычка. Объявления, которые можно использовать, следующие:

  • TODO: указывает на то, что код не был завершен. Должен указывать, что делать дальше.
  • HACK: указывает на то, что реализация кода была сокращена.
  • XXX: указывает на то, что код ошибочен и должен быть исправлен как можно скорее.
  • FIXME: указывает на то, что код содержит ошибки и должен быть исправлен как можно скорее. Чуть менее важен, чем XXX.
  • ОБЗОР: Объясните, что любые возможные изменения в коде должны быть проверены. Эти объявления могут использоваться в одном или нескольких строчных комментариях и должны следовать тем же правилам форматирования, что и общие типы комментариев.
// 好的写法
// TODO: 我希望找到一种更快的方式
doSomething();
// 不好的写法: 注释声明空格不正确
// TODO :  我希望找到一种更快的方式
doSomething();

// 好的写法
// REVIEW: 有更好的方法吗?
doSomething();
// 不好的写法: 代码和注释应当保持同样的缩进
    // REVIEW: 有更好的方法吗?
doSomething();

8. Именование

Имена переменных должны быть в верблюжьем регистре, первая буква в нижнем регистре, а первая буква каждого слова в верхнем регистре. Первое слово в имени переменной должно быть существительным (а не глаголом), чтобы избежать путаницы с функциями. Не используйте символы подчеркивания в переменных. имена

// 好的写法
const myName = 'Jack';

// 不好的写法: 大写字母开头
const MyName = 'Jack';

// 不好的写法: 动词开头
const getMyName = 'Jack';

// 不好的写法: 使用下划线
const my_name = 'Jack';

Имена функций должны быть в верблюжьем регистре. Первым словом имени функции должен быть глагол (а не существительное), чтобы избежать путаницы с переменными. Лучше не использовать символы подчеркивания в именах функций.

// 好的写法
function doSomething() {
    // 代码
}

// 不好的写法: 大写字母开头
function DoSomething() {
    // 代码
}
// 不好的写法: 名词开头
function car() {
    // 代码
}
// 不好的写法: 使用下划线
function do_something() {
    // 代码
}

Конструкторы — функции, которые создают новые объекты с помощью нового элемента soothed — также должны называться соответствующим образом в верблюжьем регистре, начиная с заглавной буквы. объект

// 好的写法
function MyObject() {

}
// 不好的写法: 小写字母开头
function myObject() {
    
}
// 不好的写法: 使用下划线
function My_Object() {
    
}
// 不好的写法: 动词开头
function getMyObject() {
    
}

Константы (переменные, которые не будут изменены) должны быть названы со всеми заглавными буквами, разделенными одним символом подчеркивания.ES6 использует const для объявления константы.

// 好的写法
const TOTAL_COUNT = 10;
// 不好的写法
const totalCount = 10;
// 不好的写法: 混合模式
const total_COUNT = 10;

Свойства объектов имеют те же соглашения об именах, что и переменные. Методы объектов имеют те же соглашения об именах, что и функции. Если свойство или метод являются закрытыми, им должен предшествовать знак подчеркивания.

// 好的写法
const object = {
    _count: 10,

    _getCount: function() {
        return this._count;
    }
}

9. Назначение

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

// 好的写法
const flag = (i < count);

// 不好的写法:遗漏圆括号
const flag = i < count;

10. Оператор равенства

Используйте === (строгое равенство) и !== (строгое неравное) вместо == (равное) и != (не равное), чтобы избежать ошибок слабого приведения.

// 好的写法
const same = (a === b);

// 不好的写法: 使用 == 
const same = (a == b);

11. Тернарный оператор

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

// 好的写法
const value = condition ? value1 : value2;

// 不好的写法: 没有赋值,应当使用 if 表达式
condition ? doSomething() : doSomethingElse();

12. Заявление

простое заявление

Каждая строка содержит не более одного оператора, все простые операторы должны заканчиваться точкой с запятой (;).

// 好的写法
const a = 1;
const b = 2;
const c = a + b;

// 不好的写法: 多个表达式写在一行
const a = 1;const b = 2;const c = a + b;

оператор возврата

Операторы возврата не должны использовать круглые скобки при возврате значения, за исключением некоторых случаев, чтобы сделать возвращаемое значение более понятным, например:

return;
return collection.size();
return (size > 0 ? size : defaultSize)

составное утверждение

Составной оператор — это список операторов, заключенных в фигурные скобки;

  • Операторы в квадратных скобках должны иметь отступ на один уровень больше, чем составные операторы.
  • Открывающая фигурная скобка должна быть в конце строки, содержащей составной оператор; закрывающая фигурная скобка должна быть на отдельной строке с тем же отступом, что и в начале составного оператора.
  • Когда круглые скобки являются частью управляющей структуры, такой как оператор if или for, все операторы, включая отдельные операторы, должны быть заключены в круглые скобки.Это соглашение упрощает добавление операторов, не беспокоясь о том, что можно забыть круглые скобки и вызвать ошибки.
  • Ключевые слова, с которых начинается оператор, например if, должны сопровождаться пробелом, а открывающая фигурная скобка должна стоять после пробела.

If выписка

if (condition) {
    statements
} else if (condition) {
    statements
} else {
    statements
}

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

// 好的写法
if (condition) {
    doSomething();
} 
// 不好的写法: 不恰当的空格
if(condition){
    doSomething();
} 
// 不好的写法: 遗漏花括号
if (condition) 
    doSomething();

// 不好的写法: 所有代码写在一行
if (condition) { doSomething(); }
// 不好的写法: 所有代码写在一行且没有花括号
if (condition) doSomething();

для заявления

for (initialization; condition; update) {
    statements
}

for (constiable in object) {
    statements
}

При использовании оператора for-in не забудьте дважды проверить hasOwnProperty(), чтобы отфильтровать элементы объекта.

пока заявление

while (condition) {
    statements
}

сделать заявление

do {
    statements
} while (condition)

оператор переключения

switch (expression) {
    case expression:
        statements
    default:
        statements
}

Каждый случай в разделе switch clang имеет отступ. Каждому случаю, кроме первого, включая значение по умолчанию, должна предшествовать пустая строка. Каждый набор операторов (кроме default) должен заканчиваться break, return, throw или однострочным комментарием, указывающим на пропуск.

// 好的写法
switch (value) {
    case 1:
       /* falls through */
    case 2:
        doSomething();
        break;
    case 3:
       return true;
    default:
       throw new Error('this should not happen');
}

оператор попытки

try {
    statements
} catch (constiable) {
    statements
} finally {
    statements
}

13. Строгий режим

Строгий режим следует использовать только внутри функций, а не глобально.

Модули ES6 автоматически используют строгий режим, независимо от того, добавляете ли вы «use strict» в заголовок модуля.

14. Объявление переменной

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

Рекомендуемое использованиеES6letа такжеconstобъявлять переменные

15. Объявление функции

Объявления функций должны быть определены перед использованием. Функция, которая не является методом (то есть не свойством объекта), должна использовать формат определения функции (не выражение функции иКонструктор функцийФормат). Перед именем функции и открывающей скобкой не должно быть пробела. Между закрывающей скобкой и правой фигурной скобкой должен быть пробел. Правая фигурная скобка должна находиться на той же строке, что и ключевое слово функции. Между ними не должно быть пробела. открывающая и закрывающая круглые скобки. Пробел. После запятой между именами параметров должен быть пробел. Тело функции должно иметь отступ на один уровень.

// 好的写法
function doSomething(arg1, agr2) {
    return arg1 + arg2;
}
// 不好的写法: 第一行不恰当的空格
function doSomething (arg1, agr2) {
    return arg1 + arg2;
}
// 不好的写法: 
const doSomething = function doSomething(arg1, agr2) {
    return arg1 + arg2;
}
// 不好的写法: 左侧的花括号位置不对
function doSomething(arg1, agr2)
{
    return arg1 + arg2;
}
// 错误的写法: 使用Function构造器
const doSomething = new Function('arg1', 'agr2', 'return arg1 + arg2');

16. Бланк

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

Разрешение на пустую строку в две строки используется в следующих случаях.

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

Однострочное разрешение на пустую строку используется в следующих ситуациях.

  • между методами
  • Локальные переменные и операторы первой строки
  • перед многострочным или однострочным комментарием
  • между логическими блоками кода в методах для улучшения читаемости кода

Пробелы следует использовать в следующих ситуациях

  • Ключевые слова, за которыми следуют круглые скобки, должны быть разделены пробелами.
  • После запятой в списке параметров должен быть оставлен пробел.
  • Операнды всех бинарных операций, кроме точки (.), должны быть разделены пробелами.Операнды унарных операций не должны быть разделены пробелами, например, унарный минус, приращение (++) ), декремент (--)
  • Выражения в выписке должны быть разделены пробелами

17. Чего следует избегать

  • Никогда не используйте новые объекты, созданные с помощью примитивных типов оболочки, таких как String.
  • Избегайте использования eval()
  • Избегайте использования оператора with. Оператор change больше не существует в строгом режиме и может быть удален в будущем.

Используйте инструменты (eslint) для обеспечения соблюдения ограничений

правила эслинта

правила eslint, определенные в .eslintrc.js, необоснованные могут быть вырезаны из правила или могут быть добавлены хорошие предложения; Основное замечание несколько:

  • Отступ кода 4 пробела
  • По умолчанию операторы должны сопровождаться точкой с запятой.
  • используйте одинарные кавычки
  • Удалите или закомментируйте оператор console.log перед отправкой кода (иначе это повлияет на отладку других разработчиков).
  • Запретить использование const, использовать es6 let, const для объявления переменных

Также есть некоторые случаи, которые не нужно обнаруживать, такие как сторонние библиотеки, фреймворки, компоненты, библиотеки пользовательского интерфейса и т. д., эти файлы можно поместить в файл .eslintignore, а обнаружение eslint можно игнорировать

Добавьте следующую строку вверху файла, чтобы отключить правила eslint для всего файла.

/* eslint-disable */

pre-commit

Перед отправкой кода будет принудительно проведена проверка кода, а код, не соответствующий спецификации, не может быть отправлен. инструкции 1. Установить из командной строки

npm i --save-dev pre-commit

2. Настроить в package.json

{
    "scripts": {
        "eslint": "eslint ./ --ext js,vue --ignore-pattern .eslintignore --cache --fix",
        "lint-message": "echo '开始 eslint 检查, 存在 error 则会拒绝提交'"
    },
    "pre-commit": [
        "lint-message",
        "eslint" // 进行eslint检查并自动修复一些简单的格式错误
    ],
}

Перед отправкой кода будет принудительно проведена проверка кода, а код, не соответствующий спецификации, не может быть отправлен.

Если у вас действительно нет времени на изменение проекта, вы можетеgit commit -m 'XXX' --no-verify 或 git commit -n 'xxx'Принудительно зафиксировать

Советы - vscode можно настроить на автоматическое сохранение ошибок eslint

vscode устанавливает плагин eslint, который настраивается в конфигурации следующим образом

{
     "eslint.autoFixOnSave": true,
     "eslint.enable": true,
     "eslint.options": {
        "extensions": [".js", ".vue", ".jsx"]
     },
     "eslint.validate": [
          {

              "language": "vue",
              "autoFix": true
          },
          {
              "language": "javascript",
              "autoFix": true
          },
          {
              "language": "javascriptreact",
              "autoFix": true
          }
      ],
}

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

Статьи и книги, приведенные в следующих ссылках, вы должны иметь хорошее время, чтобы прочитать их, что поможет вам глубоко понять важность стиля кодирования JavaScript. Всегда помните, что нормы решают большинство проблем.

Ссылаться на

Категории