Перевод Google TypeScript Style Guide
Как известно, при разработке и ведении проектов, одним из важных моментов является поддержка единого стиля в коде. Зачастую за основу берут какое-то общепризнанное руководство по стилю и дорабатывают его под свои нужды. И если в случае с 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 обладало теми же самыми проблемами. Не всем оказалось легко вникать в подобный текст, что усложняет его использование в команде разработчиков и поэтому было решено сделать перевод этого руководства. Помимо этого были и другие причины:
- Новички при чтении оригинала, часто пользуются автоматическими переводчиками, которые страдают тем, что и «should» и «must» часто переводят как «должен» — а многими это слово воспринимается «строго обязательным к исполнению», что может привести к некорректному пониманию правил руководства. Причем не все обращают внимание на стандарт RFC2119, на который ссылается руководство и в котором четко расписано применение в документации «MUST», «SHOULD», «MAY» и пр.
- В руководстве есть несколько выражений и терминов, требующих дополнительного пояснения. Например, не каждый захочет разбираться в том, что подразумевается под термином «google3».
- В руководстве присутствует несколько ошибок, которые могут ввести в заблуждение (правки они не принимают).
Разбор проблемной ситуации из оригинального руководства
Рассмотрим ситуацию с «возможной» ошибкой на примере представленного в руководстве «плохого» кода:
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. Вы можете сами ознакомиться с этим примером в онлайн-песочнице:
Т.к. еще много где используется старый TypeScript и не все знакомы с такими нюансами, я посчитал нужным прокомментировать подобные моменты в переводе.
Использование Markdown вместо HTML
Оригинальный перевод распространяется в формате HTML, что не очень удобно для подобной документации, поэтому все делалось сразу в формате Markdown (спецификация GFM), который был более подходящим под подобный контент, удобен в плане поддержки, да и в том же GitHub его можно редактировать прямо из веб-интерфейса. Но т.к. не хотелось зависеть от GitHub и его просмотрщика — сделал на всякий случай простую и минималистичную веб-страничку, собираемую из Markdown. Для оформления был взят гитхабовский Primer.css, который визуально многим знаком, легко поддерживает адаптивность и модный нынче «ночной режим» браузера.
Пара слов о использовании Primer.css для оформления документации
Сам по себе этот фреймворк достаточно любопытный и активно развивается, хотя и страдает некоторыми багами. Разрабатывает этот продукт команда из Github и успешно использует в своих проектах. Для документации, генерируемой из Markdown, там есть готовый компонент, который позволяет легко сделать вполне лаконичное отображение (с поддержкой ночной темы браузера). Я думаю, многие видели, как отображается в Github отрендеренный Markdown — так вот, это оно.
В итоге позвольте поделиться с вами ссылкой на перевод руководства Google по стилю написания кода на языке TypeScript (+ напрямую Markdown или зеркало веб-версии — просто на случай проблем с GitHub) — искренне надеюсь, что кому-нибудь это пойдет во благо и принесет пользу.
P.S. Перевод делал из-за необходимости в нем (я не профессиональный переводчик, да и гуманитарные навыки хромают). При переводе важно было не отходить от оригинала, поэтому текст местами может читаться тяжело. Если в переводе вы обнаружите какие-либо ошибки, неточности или моменты, которые могут потребовать разъяснения, вы можете указать об этом в репозитории перевода (issue, pull request и пр.).