Почему и как нужно документировать модульный JavaScript!
В прошлом посте я говорил о том, почему мы должны модулировать наш JavaScript:
Следующий шаг на пути к JavaScript
Самая универсальная истина, которую я могу придумать:« Мы все хотим меньше сосать . medium.com»
В этом посте мы действительно запачкаем руки!
Почему мы должны документировать 📝
Когда мы пишем модульный JavaScript и начинаем перемещать функции в отдельные файлы, вам, вероятно, будет труднее использовать эти функции, не глядя на них. С помощью некоторой магии документации мы можем легко узнать:
- что делает функция
- какие параметры он может принимать
- что возвращает функция
И поверьте мне, если у вас есть код старше 3 месяцев, вам всегда придется перечитывать его, чтобы понять его. Это может быть намного проще, если у вас есть собственная встроенная документация!
Кроме того, поскольку в этой серии статей мы будем работать над написанием нашего первого модуля NPM, документация - это добрый жест для всех, с кем вы могли бы поделиться своим кодом. 😊
Наш пример функции
Давайте посмотрим на пример функции, которая лучше всего работает в модульном исполнении.
Например. у нас есть приложение, которое использует большие числа с множеством десятичных знаков, и нам нужно только показать число, округленное в большую или меньшую сторону с максимальным x десятичными знаками. В качестве примера мы хотим, чтобы число 0.12345 стало 0.123.
Простая интеграция может быть:
Теперь мы можем сделать roundDecimals(0.12345, 3) и вернуться 0.123.
Экспорт и импорт
Это легко, и я уверен, что любой, кто это читает, вероятно, уже знает, как это сделать. 😉
(но быстрый обзор) Просто сохранив вашу функцию в отдельном файле с именем, например. roundDecimals.js вот так:
Это позволяет импортировать и использовать эту функцию в любом другом файле следующим образом:
Однако основная проблема заключается в том, что чем больше мы модулируем наш код, тем больше файлов у нас ... Это часто раздражает поиск в этих других файлах, что именно это была функция, какие параметры она получает и т. Д. Давайте решим это с помощью магии документации!
Функциональность текстового редактора по умолчанию
Большинство текстовых редакторов имеют неплохие готовые функциональные возможности для документации. Я собираюсь привести короткий пример для VSCode, что происходит, когда вы наводите курсор на roundDecimals() из нашего примера выше:
А при удерживании command (в macOS) становится еще лучше:
Затем мы можем даже щелкнуть имя функции, чтобы перейти к этому файлу.
Однако в документации по умолчанию отсутствует то, что у нас нет никаких объяснений того, что функция делает, возвращает или принимает в качестве параметров. 😕
Хорошо, мы можем видеть всю функцию, удерживая команду, но это быстро становится неудобным, когда ваши функции длиннее.
Добавьте свою магию документации 🧙♂️ 💫
Чтобы получить лучшую обратную связь о том, что функция делает, возвращает и принимает в качестве параметров, нам необходимо добавить нашу собственную документацию.
Я покажу, как легко добавить эту информацию с помощью стандарта JSDoc. Сначала вам нужно найти плагин для текстового редактора под названием ‘document this’. С помощью этого плагина вы можете щелкнуть правой кнопкой мыши любую функцию и выбрать документировать. Это дает вам красиво отформатированный блок документации, который выглядит следующим образом:
Теперь мы можем просто ввести информацию о том, что функция делает, возвращает и принимает в качестве параметров. См. Пример ниже:
После добавления этой информации посмотрите, как полностью изменилась наша функция обратной связи в VSCode:
Это может немного отличаться в зависимости от того, какой текстовый редактор вы используете, но большинство современных довольно хорошо справляются с передачей документации по функциям!
Фух! Это было проще, чем вы ожидали, да! Поверьте, небольшая работа с документацией имеет большое значение!
Живи долго и процветай 🎉
С уважением,
- Лука Бан (github)
