Skip to Content
⚠ Документация в разработке
СоглашенияГлавное

Стандарты написания кода “Лэйзи Энд Фокусед”

“Лень подчинила себе процессы, пока мы фокусировались на обязанностях”
— Valentin Bird ~ придумано за минуту.

“Код, придерживающийся единой концепции и стиля, — элегантный”
— FOCKUSTY ~ красота всему голова.

Правила “простого кода” по Роберту Мартину:

  • Проходит все тесты
  • Не содержит дубликатов
  • Выражает все концепции системы
  • Не содержит лишний сущностей.

1. Наименование

  1. Использовать определенную нотацию в соответствии с языком программирования.
    1. JSON — camelCase.
    2. Database — snake_case.
  2. Использовать в названиях аббревиатуры как одно слово.
    1. camelCase — getApiUrl.
    2. snake_case — get_api_url.
    3. kebab-case — get-api-url.
    4. И их аналоги (UpperCamelCase, SCREAMING_SNAKE_CASE, camel-Kebab-Case и др).
  3. Наименование должно отражать то, что оно делает.
  4. Наименование не должно содержать артиклей.
  5. Наименование не должно содержать дезинформации.
  6. Желательно избегать сокращений, исключение составляет общепринятая нотация, например: i, j, k в циклах, но даже их лучше писать полностью при возможности. Поясните!
  7. Желательно использовать удобно произносимые наименования.
  8. Нежелательно добавлять избыточный контекст в наименования.
  9. Обязательно именовать классы, типы и интерфейсы в UpperCamelCase.
  10. Обязательно именовать на английском языке, транслит запрещается.
  11. Обязательно именовать константы в SCREAMING_SNAKE_CASE.
  12. Обязательно именовать в американском английском диалекте.

2. Переменные и поля

  1. Объявление данных ближе к контексту (Объявите переменную близко к тому, где она используется).
  2. Если переменное/поле содержит булево значение, то наименование должно содержать прошедшее время: actived, available, outdated. Если это невозможно, то добавляйтесь префикс is: isAdmin, isUser.

3. Функции и методы

  1. Имя функции должно содержать глагольную часть.
  2. Каждая линия функции должна быть на одинаковом уровне абстракции. Поясните!
  3. Функция должна делать только одно действие.
  4. Функция должна принимать не более трёх аргументов.
  5. Функция не должна быть больше 100 строк, оптимальная длина: 20-30 строк — вся функция должна умещаться на экране.
  6. Функция не должна изменять состояние параметров, которое ей было передано.
  7. Функция не должна возвращать null или undefined, когда это не предусмотрено логикой, желательно возвращать ошибку (throw new error) или false, если логика позволяет.
  8. Функция не должна возвращать код ошибки.
  9. Функции желательно проверять параметры и возвращаемые значения.
  10. Функции нежелательно принимать булев аргумент.
  11. Желательно избегать рекурсии в функциях.
  12. Если из функции можно извлечь функцию, то нужно извлечь.
  13. Если функция возвращает булево значение, то наименование должно содержать вопрос: isActive, isAvailable. Если наименование содержит существительное, то добавляйте префикс validate к наименованию: validateAdmin, validateUser.
  14. Если функция выступает в роли обработчика событий, то наименование должно содержать префикс on: onClick, onMove.

4. Классы

  1. Имена классов не должно содержать глагольную часть, так как оно должно представлять собой существительные и их комбинации.
  2. Модификаторы доступа у полей по умолчанию: private.
  3. Обязательно наименование класса в UpperCamelCase или в соответствии с языком программирования.
  4. Обязательно инициализация поля в конструкторе.
  5. Обязательно использовать единый стиль исполняющего методова, в зависимости от проекта. По умолчанию: execute. Возможные варианты: execute, run, initialize (init).
  6. Методы класса не должны быть объявлены через лямбда-синтаксис. Чё?

5. Циклы

  1. Циклы должны содержать определенное количество итераций.

6. Импорт и экспорт

  1. Нельзя импортировать и экспортировать одновременно. Поясните!
  2. Импортировать типы/абстракцию как типы. Не понял
  3. Всегда экспортировать дефолтный экспорт вместе с недефолтным (имеются исключения из-за фреймворков).
  4. Всегда выносить импорт типов.
  5. Избегать require.
  6. Избегать import * as {name}.
  7. Обязательно сортировать импорты.
  • Также импортировать сначала типы (типы, интерфейсы, абстракные классы)
  • После данные (функции, переменные, классы)
  • А в конце вспомогательные файлы (.txt, .json, .css) и импорты-инициализаторы (за редким исключением). Ничего не понял, но очень интересно
  1. Если есть возможность импортировать статично, то нужно импортировать статично.

7. Код

  1. Извлекайте функции.
  2. Переименовывайте в поиске лучшего названия.
  3. Удаляйте дубликаты кода.
  4. Снижайте уровень вложенности кода.
  5. Используйте пояснительные переменные. Поясните!
  6. Код не должен содержать лишнии комментарии (Разрешается писать документацию через специальные комментарии).
  7. Код не должен содержать закомментированный код.
  8. Код не должен содержать магический чисел, строк…
  9. Желательно не опускать фигурные скобки. Поясните!
  10. Желательно иметь маленький уровень табуляции (идентации).
  11. Уровень табуляции зависит от проекта. Стандартный уровень табуляции в команде: 2 пробела.

8. Компиляция

  1. Желательно компилировать код, находящийся в разработке, каждый день для проверки на ошибки.

Пояснения

Caution

Если используете сокращения, то используйте их во всём коде одинаково.

  • 1.6. “Желательно избегать сокращений, исключение составляет общепринятая нотация…” — Все допустимые сокращения:

    • add — addition.
    • app — application.
    • arr — array.
    • asc — ascending.
    • auth — authentication.
    • bool — boolean.
    • cfg/config — configuration.
    • char — character.
    • const — constant.
    • desc — descending.
    • dev — development.
    • dir — directory.
    • env — environment.
    • func — function.
    • id — identifier.
    • img — image.
    • init — initialize.
    • int — integer.
    • max — maximum.
    • min — minimum.
    • msg — message.
    • nav — navigation.
    • num — number.
    • obj — object.
    • req — request.
    • res — response.
    • rm/rem — remove.
    • src — source.
    • temp — temporary.
    • up — update.
    • var — variable.

    Также допускается использование метапеременных из математики: a, b, c, d, e, f; x, y, z, w; i, j, k.
    И мета-чисел: 23, 42, 47, 69, 666, 0815, 1337, 4711.
    Также допускается сокращения до одной буквы, когда используются методы массивов/объектов/…, например:

    const numbers = [1, 2, 3, 4, 5, 6];
const otherNumber = numbers.map((n) => n * 2);

    Но только тогда и только тогда, когда переменная понятна из контекста и код не выглядит большим и громовским. Давай обратно!

  • 3.2. “Каждая линия функции должна быть на одинаковом уровне абстракции” — Каждая часть функции должна, как и функция, выполнять работу над действием функции. Хочу назад!

  • 4.6.

    // Так нельзя
class ExampleClass {
  hello = () => {
    console.log();
  }
}
 
// Так можно
class ExampleClass {
  hello() {
    console.log();
  }
}

    Да без проблем!

  • 6.1.

    export import("some-path");

    Всё понятно!

  • 6.2.

    import type { SomeClass, SomeType, SomeInterface } from "path-to";
 
// SomeType и SomeInteraface всегда импортируются, как типы
// SomeClass только в том случае, если он используется, как тип

    Сразу понял!

  • 6.7.

    import "dotenv/config"; // init-импорт, который обязательно должен быть в начале
 
import type {
  SomeType,
  SomeInteraface
} from "path-to";
 
import {
  SomeClass,
  SOME_CONTENT
} from "path2";
 
import package from "package.json";
 
import "style.css";

    АААААААААААААА

  • 7.5. “Использовать пояснительные переменные” — Объявлять переменные, когда записываешь условие или результат функции.

    const transferAllowed =
  hasSufficientBalance(account.balance, transfer.amount) &&
  account.isActive();
 
if (transferAllowed) {
  console.log("Transfer successful.");
} else {
  throw new Error("Transfer can not be completed.");
}

    Угу…

  • 7.9. “Желательно не опускать фигурные скобки” — см. снимок экрана.

    // Без опускания фигурных скобок
if (transferAllowed) {
  console.log("Transfer successful.");
} else {
  throw new Error("Transfer can not be completed.");
}
 
// С опусканием фигурных скобок
if (transferAllowed) console.log("Transfer successful.");
else throw new Error("Transfer can not be completed.");

    При этом допускается опускание скобок, если сразу после идёт возврат функции или вброс ошибки (заканчивание логики). Хорошо!

Источники вдохновения

  • Книга “Чистый код” — Роберт Мартин.
  • YouTube-видео “Как писать чистый код” — Vlad Mishustin.
  • YouTube-видео “Пиши код как NASA” — Си-шный Поц.
  • YouTube-видео “Правила написания кода от Дяди Боба” — Си-шный Поц.
Last updated on
Уютный старт 🤗Документация