Какое из популярных руководств по написанию кода стоит выбрать за основу для проекта на TypeScript

Я думаю ни для кого не секрет, что в среде веб-разработки TypeScript (TS) набирает обороты, ибо чем больше кодовая база, тем большую роль начинает играть типизация. Кто пытался писать на JavaScript (JS) большие проекты, тот особенно знаком с этой проблемой. Да вы можете сказать, что есть же JSDoc - но он даже и близко не дает того уровеня контроля, который предоставляет в сравнении с ним TS.

Естественно, при разработке проекта, крайне рекомендуется придерживаться единого стиля написания кода (style guide) и естественно за основу берут одно из популярных соглашений по стилю написания кода и адаптируют это соглашение под свои нужды. Для PHP это обычно PSR, для Python - PEP8, для JS часто берут Airbnb JavaScript Style Guide и т.д.

Как вы думаете, какое руководство часто берут за основу при разработке на TypeScript? Ну конечно же Airbnb JavaScript Style Guide! Да, это не шутка, что для разработки на TypeScript часто берут именно руководство по написанию JavaScript кода.

Почему для написания кода на TypeScript часто берут Airbnb JavaScript Style Guide?

Причин для такого решения несколько:

• Как известно, TS расширяет синтаксис JS и является обратно совместимым с ним и поэтому если вы не используете всех возможностей TS, а применяете его только для проверки типов в аргументах, то руководство по написанию кода на JS в определенной мере подходит и к TS.
• Большинство разработчиков на TS перешли на него с JS и соответственно по привычке используют уже готовый и настроенный на работу линтер.
• Есть программы, которые переписываются на TS. Даже автоматическое переворматирование всей кодовой базы на новый "code style guide" может принести большое количество проблем и неожиданностей. Поэтому в таком проекте JS style guide принят как унаследованное решение (legacy).

В общем-то ничего плохого нет в использовании этого решения для TS. Но хочу отметить, что это решение никак не регламентирует стиль написания для интерфейсов, типов, перечислений (enum) и многого другого, что добавляет TS. Поэтому в таком случае для линтеров добавляют специфичные правила для TS, например через тот же TypeScript-ESLint.

Но линтеры это одно, а документация это другое. Хочется все-таки использовать в работе регламентированный именно для TS стиль написания, с публичной документацией и с поддержкой популярных инструментов (например того же ESLint). Поэтому следует обратить внимание на другое решение, такое как Google's TypeScript style guide.

"Google's TypeScript style guide" как руководство по стилю написания для TypeScript

Одно из самых главных преимуществ Google's TypeScript style guide состоит именно в "специалитете" руководства, ибо оно заточено конкретно под TS, а не под JS. Для JS у Google есть отдельное руководство Google JavaScript Style Guide.

Приведу один явный пример для сравнения. Как известно, недавно в JS добавили приватные свойства и методы с использованием знака "#".

// JS private property
class Cat {
  #ident = 1;
}

Согласно GTS, в TS следует писать так:

// TS private property recommended declaration
class Cat {
  private ident = 1; // "private" instead "#"!
}

А знаете почему? В коде вы нередко будете использовать не только частные ("private") свойства и методы, но и защищенные("protected"). Я честно говоря до сих пор не понимаю, зачем в JS ввели "#" вместо привычного для других языков "private", а тот же "static" оставили ключевым словом... Хотя пофиг, ибо у нас есть TS 😊.

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

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

Возьмем пример на Vue 3, в котором вы принимаете за основу "Google's TypeScript style guide" и Vue Official Style guide и пр.. К сожалению на момент написания статьи некоторые правила не совсем корректно работают друг с другом (особенно в однокомпонентных шаблонах), поэтому один фиг приходится погружаться в настройку ESLint и прописывать не только плагины, но и следить за порядок их выполнения, т.к. по мере их инициализации они переопределяют некоторые правила ESLint:

{
  ...,
  "extends": [
    ...,
    "plugin:vue/base",
    "./node_modules/gts",
    "plugin:vue/vue3-essential",
    "plugin:vue/vue3-strongly-recommended",
    "plugin:vue/vue3-recommended",
    "eslint:recommended",
    "@vue/typescript",
    ...
  ],
  "rules": {
    ...,
    "no-undef": "off",
    "no-unused-vars": "off",
    "@typescript-eslint/no-unused-vars": ["error"],
    "node/no-unsupported-features/es-syntax": "off",
    "node/no-missing-import": "off",
    "vue/max-attributes-per-line": "off",
    "vue/html-closing-bracket-newline": "off",
    "vue/html-indent": "off",
    "vue/html-self-closing": "off",
    ...
  },
  ...,
}

Но пугаться этого не надо, т.к. стиль написания кода в проектах не меняется каждый день. Соответственно в компании, вы можете на всю команду согласовать единый стиль и просто раздать всем эти правила в виде конфига.

Заключение

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

В общем получилось выделить три подхода в данном случае:

• Если вы используете TS только для простейшего контроля типов - вам наверное будет более удобен Airbnb JavaScript Style Guide.
• Если вы не стесняетесь использовать все возможности TS - то стоит присмотреться к Google's TypeScript style guide.
• Можно заморочиться и собрать сборную солянку из рекомендаций обоих руководств, только при этом не стоит забывать это все вынести в документацию.

Есть и другие руководства, которые вы можете брать за основу, тут как вам удобно. Главное, чтобы по проекту был принят единый стиль, которого должна придерживаться вся команда разработки, что в свою очередь существенно влияет на качество кода. А качественный код - это всегда хорошо 😉