Здравствуйте, уважаемые читатели Хабра!

Как известно, при разработке и ведении проектов, одним из важных моментов является поддержка единого стиля в коде. Зачастую за основу берут какое-то общепризнанное руководство по стилю и дорабатывают его под свои нужды. И если в случае с JavaScript уже есть множество общеизвестных руководств, то с TypeScript дела обстоят несколько иначе. Конечно, если у вас в коде особенности TypeScript используются в мизерной доле, отдельное руководство по нему будет излишним, но если вы хотите использовать TypeScript более серьезно — рекомендации из готового руководства могут оказаться вполне полезными.

В начале 2021 года разработчики из Google выложили у себя в репозитории руководство по стилю TypeScript (Google TypeScript Style Guide), в котором было описано множество специфических правил применения этого языка, с учетом их опыта. Т.к. я уже сталкивался с их GTS (сборная солянка из форматтера и линтера для TS), мне стало любопытно ознакомиться с этим руководством, тем более оно, что логично, опирается на уже существующее руководство по JavaScript (Google JavaScript Style Guide). Даже если это руководство и не использовать в полной мере, оттуда вполне можно почерпнуть несколько полезных правил.

Причины создания перевода

Найти перевод этого руководства для TypeScript мне не удалось, но зато на глаза попалась статья на Хабре: «Перевод Google JavaScript Style Guide» от пользователя @RostislavDugin, в которой был представлен перевод руководства по стилю для JavaScript. В статье автор описал проблемы с которыми столкнулся при переводе того руководства и текст которого он охарактеризовал так:

"Написано довольно сухо, иногда сложными конструкциями и некоторые моменты даже спустя какое-то время приходится перечитывать по несколько раз, чтобы точно понять смысл"

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

1. Новички при чтении оригинала, часто пользуются автоматическими переводчиками, которые страдают тем, что и «should» и «must» часто переводят как «должен» — а многими это слово воспринимается «строго обязательным к исполнению», что может привести к некорректному пониманию правил руководства. Причем не все обращают внимание на стандарт RFC2119, на который ссылается руководство и в котором четко расписано применение в документации «MUST», «SHOULD», «MAY» и пр.

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

3. В руководстве присутствует несколько ошибок, которые могут ввести в заблуждение (правки они не принимают).

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

Рассмотрим ситуацию с «возможной» ошибкой на примере представленного в руководстве «плохого» кода:

export let foo = 3;

window.setTimeout(() => {
  foo = 4;
}, 1000);

В оригинале указано, что «в чистом ES6, foo мутабельно и импортеры будут наблюдать изменение через секунду, а в TS при реэкспортировании данного кода, импортеры не увидят изменений».

К сожалению, этот пример может некоторых сбить с толку, ибо в TS 3.9, при использовании ненативных модулей на подобии CommonJS, данное поведение было приведено в соответствии с ES6, т.е. в TS < 3.9, foo через секунду будет равен 3, а в TS >= 3.9, foo будет 4. Вы можете сами ознакомиться с этим примером в онлайн-песочнице:

• пример с TS >= 3.9

• пример с TS < 3.9

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

Использование Markdown вместо HTML

Оригинальный перевод распространяется в формате HTML, что не очень удобно для подобной документации, поэтому все делалось сразу в формате Markdown (спецификация GFM), который был более подходящим под подобный контент, удобен в плане поддержки, да и в том же GitHub его можно редактировать прямо из веб-интерфейса. Но т.к. не хотелось зависеть от GitHub и его просмотрщика — сделал на всякий случай простую и минималистичную веб-страничку, собираемую из Markdown. Для оформления был взят гитхабовский Primer.css, который визуально многим знаком, легко поддерживает адаптивность и модный нынче «ночной режим» браузера.

В итоге позвольте поделиться с вами ссылкой на перевод руководства Google по стилю написания кода на языке TypeScript (+ напрямую Markdown или зеркало веб-версии - просто на случай проблем с GitHub) — искренне надеюсь, что кому-нибудь это пойдет во благо и принесет пользу.

P.S. Перевод делал из-за необходимости в нем (я не профессиональный переводчик, да и гуманитарные навыки хромают). При переводе важно было не отходить от оригинала, поэтому текст местами может читаться тяжело. Если в переводе вы обнаружите какие-либо ошибки, неточности или моменты, которые могут потребовать разъяснения, вы можете указать об этом в репозитории перевода (issue, pull request и пр.).