Что, если я скажу вам, что существует некий компромисс между простым Javascript со всей его гибкостью и структурой TypeScript? В этой краткой статье мы познакомимся с решением, которое мне нравится использовать в личных и профессиональных проектах.
Условие:
- Некоторые базовые знания JavaScript/Typescript
- Код Visual Studio (рекомендуется)
- NodeJs, Deno или другие
Но сначала позвольте мне представить несколько концепций, прежде чем углубляться в конкретные примеры.
Введение
JSDoc – это API документации, созданный для JavaScript. Идея состоит в том, чтобы поместить некоторые аннотации в комментарии, чтобы объяснить: что, почему, кто и т.д.; назначение: переменной, функции, условия и т. д. Подробнее о JSdoc см. здесь и здесь.
Файл jsconfig.json позволяет вам установить некоторую информацию о конфигурации для проекта JavaScript в среде IDE, которая использует технологию LSP (например, VS Code). Мы не собираемся объяснять здесь все возможности, но это очень интересный способ настроить ваш проект с дополнительной пользовательской конфигурацией. Узнать больше можно здесь.
Цель этого файла в этом руководстве — установить для параметра «checkJs» значение «true».
«Когда checkJs включен, в файлах JavaScript сообщается об ошибках. Это эквивалентно включению // @ts-check в начало всех файлов JavaScript […]». — typescriptlang.org
{ "compilerOptions": { "checkJs": true } }
Я думаю, вы начинаете понимать, к чему все идет: мы собираемся использовать проверку типов TypeScript в наших файлах JavaScript. И с учетом сказанного, JSDoc позволит нам быть более точными и сложными во всем, что мы хотим определить.
Таким образом, целью этой статьи будет добавление некоторых объяснений к решению, которое я действительно считаю немного недооцененным и мало обсуждаемым.
С учетом сказанного, мы собираемся проиллюстрировать на примерах настройку конкретных элементов, которые я часто использую в своих проектах. Конечно, вы не увидите 100% всех возможностей, но у вас будет некоторый ключ, чтобы начать использовать его в своих проектах.
Чтобы лучше понять их, я действительно предлагаю вам скопировать примеры в вашу IDE, чтобы увидеть, как работают автозаполнения и ошибки.
Типизированная переменная
Типизированная переменная — это самый первый способ представить JSDoc. С аннотацией «@type» вы можете применить любой тип к переменной. Таким образом, вы можете гарантировать, что разработчик сможет иметь правильное автозаполнение (более связное, чем если бы тип был «любой») и не захочет присваивать ему неправильное значение.
Вот несколько основных примеров, которые демонстрируют некоторые случаи, которые вы хотели бы использовать.
Типизированная функция
После типизированной переменной и понимания основ того, как применить тип к элементу, следующий уровень — типизированные параметры функции.
На мой взгляд, это может быть наиболее важной стратегией для использования с JSDoc, поскольку она позволяет вам быть действительно явным и, возможно, избежать проверки типов параметров внутри функции с некоторыми уродливыми условиями, которые отягощают ваши логические (даже если, конечно, JSDoc и CheckJs не блокируют компиляцию JS, поэтому вы все равно можете использовать неправильные типизированные аргументы, и это будет работать).
Для этого мы будем использовать несколько ключевых слов: «@param», «@returns» и «@template».
Типизированный интерфейс
«@typedef» — очень полезная аннотация для документирования пользовательских сложных типов, которые вы хотите использовать несколько раз в своем коде. Например: раньше объект с некоторыми свойствами определялся как простая переменная и как параметр функции.
Вы также можете использовать «@callback», что очень похоже на то, как работает «@typedef», но полезно для определения типов функций.
Типизированные элементы класса
И последнее, но не менее важное: вы также можете добавить аннотацию, чтобы сделать элементы вашего класса более понятными. Если вы знакомы с ООП, то легко поймете, для чего они нужны: «@private», «@public», «@protected». ", "@override", "@extends" и "@implements".
Примечание: также может быть хорошей идеей использовать атрибут закрытого класса, если ваша среда достаточно новая.
Заключение
Я действительно думаю, что JSDoc — интересная стратегия для добавления типизированных элементов в проект JavaScript вместо использования TypeScript. В JSDoc есть гораздо более интересные вещи («@example», «@deprecated», «@author» и т. д.), и если вы не знаете об этом намного больше, я действительно приглашаю вас быстро прочитать документацию, это поможет вам написать более описательный код, даже на TypeScript!
Конечно, у этого решения есть свои преимущества, но также и недостатки, и в этот момент вам может быть интересно:
«Почему я должен использовать их вместо перехода на TypeScript?»
На мой взгляд, реального ответа нет: вы вольны выбирать. И не заставляйте меня говорить то, чего я не говорил, мне нравится использовать TypeScript для некоторых проектов, но иногда я просто чувствую, что будет достаточно просто написать простой JavaScript и добавить минимум типизированных элементов с помощью JSDoc, чтобы улучшить мой код.
Другой способ увидеть это, если вы хотите добавить типизированный материал в уже существующий проект JavaScript. В этом случае вам не нужно преобразовывать его в TypeScript, а просто настройте «jsconfig.json» с помощью «checkJs». На этом этапе вы сможете исправить проблемы с типизированными ассоциациями (вызов функции, назначение переменных) и, поверьте мне (поскольку я уже это делал), особенно если вы новичок, как я, вы столкнетесь с такими проблемами.
В заключение я бы сказал, что JSDoc может облегчить эксплуатацию машиной, интерпретацию человеком и понимание во время обмена. Так что не забудьте добавить JSDoc в следующий раз, когда захотите поделиться с кем-то кодом 😉.
Вот и все! Большое спасибо за прочтение моей первой статьи. Также особая благодарность QUEMARD Maël за помощь в написании этой статьи и FERREIRA Marianne за исправление моего опасного английского.
Дайте мне знать ваши мысли в комментариях!