Документирование проектов Angular

Оригинальная фотография обложки, сделанная Янко Ферличем на Unsplash.

Цель документирования

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

  1. Трудности при приеме на работу: когда новые члены команды присоединяются к вашей организации, существующая документация может сэкономить много времени, объясняя, что есть что и как все работает.
  2. Путаница для существующих разработчиков: Часто разработчикам приходится работать над кодом, который был написан другими. Хорошо документированный фрагмент с примерами и инструкциями также может помочь сэкономить время, в то время как отсутствие документации может привести к медленной разработке и даже ошибкам из-за недопонимания.
  3. Трудности с менеджерами и заинтересованными сторонами: Во многих случаях, когда менеджеры хотят улучшений, они могут задавать вопросы о том, как работают существующие функции, или уточнять нюансы (например, разрешения или крайние случаи). Изучение существующей документации может, опять же, сэкономить время и проблемы.

Учитывая это, давайте сначала рассмотрим, что важно в документации для любого проекта (не обязательно Angular), а затем погрузимся в конкретные инструменты и практики, которые могут помочь в документировании проектов Angular в частности.

Некоторые правила для документации

По моему опыту, документирование — это специальный процесс, который должен быть конкретным и придерживаться определенных правил. Вот несколько важных соображений:

  1. Всегда документируйте крайние случаи и странные нюансы: если часть вашего приложения ведет себя несколько неожиданным образом, или, возможно, часть кода структурирована неожиданным образом из-за специфического бизнес-требования, обязательно укажите это в документации.
  2. Держите документацию рядом с тем, что документируется: в проектах Angular комментарии JSDoc могут использоваться для документирования компонентов, страниц и т.д. поверх исходного кода, что очень полезно и экономит время.
  3. Не передокументируйте: нет необходимости описывать каждое свойство класса, особенно если его название самоочевидно. isDialogVisible: boolean достаточно понятно; сосредоточьтесь на частях, которые могут быть ошибочными
  4. Используйте инструменты для создания веб-сайтов документации: для больших проектов наличие отдельного места, где все документировано, является лучшей практикой и может помочь при приеме новых участников.
  5. Используйте точные и четкие формулировки: не будьте слишком артистичны, постарайтесь передать смысл какого-то фрагмента кода кратко, но понятно.
  6. Если у вас есть процесс рассмотрения запросов на исправление (pull request review/peer-review), обязательно включите рассмотрение документации как часть рассмотрения кода; убедитесь, что люди, которые не работали над написанием документации, достаточно хорошо понимают то, что было задокументировано.
  7. Предоставляйте примеры! Примеры очень полезны для многократно используемых функций и/или компонентов и обеспечивают быстрый способ для других разработчиков начать работу.

Теперь, помня об этом, давайте рассмотрим документирование проектов Angular.

Документация для приложений Angular

Что документировать?

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

  1. Модули в целом, особенно функциональные модули. Такие названия, как UsersModule или DocumentsModule, обычно самоописательны, нет необходимости тратить время на их подробное объяснение.
  2. Вызовы API в методах служб. Обычно эти части кода очень описательны, взгляните на следующий пример, из него совершенно очевидно, что делают эти методы, в вашем проекте их, вероятно, сотни:
@Injectable()
export class UsersService {
  constructor(private readonly http: HttpClient) {}

  getUserById(id: number) {
    return this.http.get<User>(`api.ourprojectapi.com/users/${id}`);
  }
}
Войти в полноэкранный режим Выход из полноэкранного режима
  1. Модели/классы, связанные с бизнес-логикой: опять же, достаточно самоописательные, нет необходимости объяснять, что такое UserModel, если только нет каких-то особых нюансов.
  2. Перечисления, если только они не имеют двусмысленных названий (в этом случае сначала изучите, можно ли улучшить именование).
  3. Если вы используете стороннюю систему управления состоянием (например, NgRx или NgXs), то документирование основных шаблонных вещей, таких как редукторы или действия, не требуется, но некоторые вещи, такие как Effects в NgRx, могут потребовать некоторых пояснений в определенных случаях.

Теперь давайте рассмотрим вещи, которые определенно должны быть задокументированы:

  1. Компоненты бизнес-логики (также известные как контейнер), которые получают данные, создают формы, обновляют DOM и так далее. Опишите, что делают эти компоненты, где они используются. В случае с компонентами страницы (когда у вас есть маршрут, указывающий на нее), может быть полезно описать, какой именно маршрут указывает на нее, какие параметры она получает, какие (если есть) разрешенные данные используются и так далее.
  2. Многократно используемые компоненты: тщательно документируйте эти типы компонентов, поскольку они будут использоваться множеством других разработчиков, для которых их замысел может быть непонятен. Документируйте испускаемые события и приводите примеры. Посмотрите на этот пример, должно быть понятно, что делает компонент:
/**
 * This component displays a loading spinner over a block of content, 
 * in a dimmed overlay. Content inside the component is projected,
 * and a boolean Input `loading` displays the spinner at will.
 * Projected content is blocked from interaction when `loading`
 * is set to `true`
 * 
 * Usage example: 
 * @example
 * <app-loader [loading]="loading">
 *   <div>
 *      Content goes here
 *   </div>
 *   <button (click)="loading = true; getContent()">
 *     Get new content
 *   </button>
 * </app-loader>
*/
@Component({
    selector: 'app-loader',
    template: `
        <div #wrapper [class.loading]="loading">
            <ng-content></ng-content>
            <div class="blocker" *ngIf="loading">
                <loader-icon></loader-icon>
            </div>
        </div>
    `
})
export class Loader {
    @Input() loading = false;
}
Вход в полноэкранный режим Выход из полноэкранного режима
  1. Использование труб, связанных с бизнес-логикой. Возьмем этот пример, здесь труба определяет, прикреплен ли определенный элемент к верхней части экрана при сопоставлении с другим определенным элементом:
/**
 * This pipe takes a look at a list of items
 * (Orders, Shipments or Products)
 * and determines if it contains items that match with
 * those in an AssignmentList,
 * so that it can be displayed
 * as pinned at the top of the page
 *
 * @example
 * <!-- in Order List page, for example -->
 * <div>{{ products | isPinned : currentAssignment }}</div>
*/
@Pipe({
  name: 'isPinned',
})
export class IsPinnedPipe implements PipeTransform {
  transform<T>(
    items: { propertyName: T; id: number }[],
    item: T,
  ): boolean {
    return items.some(i => i.propertyName === item);
  }
}
Вход в полноэкранный режим Выход из полноэкранного режима
  1. Пользовательские сервисы с их методами, например, утилита с общими методами, или обертки вокруг родной функциональности, например, если у вас есть LocalStorageService, обязательно подробно документируйте его.
  2. Документируйте случаи ошибок, когда это необходимо, например, если метод с вызовом API может привести к ошибке разными способами, упомяните об этом в описании метода.

Конечно, этот список ни в коем случае не является исчерпывающим, но выполнение хотя бы этих пунктов может сэкономить вам время и проблемы.

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

Как писать документацию

Написание документа довольно похоже на написание эссе или статьи, но здесь нужно стараться быть еще более точным и кратким. Вот несколько правил, которые помогут в этом:

  1. Не затягивайте: слишком много текста, и разработчики начнут пропускать потенциально важную информацию.
  2. Используйте простой язык: не пытайтесь выпендриться, документация должна быть прагматичной инструкцией, а не поэзией.
  3. Используйте аннотации JSDoc, такие как @description, @example и т.д.
  4. Используйте ссылки там, где это уместно: например, при использовании стороннего компонента ссылка на страницу его документации может быть очень полезной.
  5. И опять же, приводите примеры, где это уместно, показывайте, а не рассказывайте, как что-то должно быть сделано на практике.

Важным первым шагом является написание страницы README. Эта страница служит отправной точкой для новых разработчиков и документом по внедрению. Опишите, о чем проект, какие инструменты используются, как установить и запустить проект, каковы основные компоненты приложения и другие важные вещи, которые разработчики должны знать с самого начала при работе с вашим проектом.

Если вы начинаете документировать проект в первый раз, хорошей идеей будет просмотреть документацию по популярным фреймворкам/библиотекам и посмотреть, как люди обычно документируют вещи. Например, сайты документации по RxJS, NgRx и самому Angular могут быть очень полезны для развития ваших навыков документирования программного обеспечения.

Например, посмотрите на структуру и язык страницы документации для оператора map в RxJS. Здесь есть краткое описание, описание типов параметров и возвращаемых типов (их можно автоматизировать — подробнее об этом позже), подробное описание с иллюстрацией и пример со ссылками на связанные вещи. Обычно вам не нужна такая изощренность, особенно при работе с корпоративными продуктами, но в целом это хорошая структура, которой стоит придерживаться.

Какие инструменты использовать

Наконец, мы подошли к моменту, когда хотим, чтобы наши документы с комментариями JSDoc превратились в полномасштабный сайт документации, которым мы можем поделиться с новыми разработчиками вместо предоставления длинных документов Word, или который может быть использован командой для поиска объяснений и направлений во время разработки. К счастью, существуют замечательные инструменты, которые помогают нам создавать такие сайты легко, с помощью всего лишь одной консольной команды. Сегодня мы изучим один из таких инструментов под названием Compodoc, который представляет собой генератор сайтов документации, специально разработанный для проектов Angular (он также поддерживает Nest и Stencil, но мы сосредоточимся на Angular).

Давайте немного исследуем и попробуем создать сайт документации из проекта Angular. Если у вас на компьютере есть удобное приложение Angular (возможно, домашний проект), просто следуйте этой инструкции:

Обратите внимание: даже если в вашем приложении нет документации, Compodoc создаст сайт, описывающий все компоненты, директивы, сервисы, трубы и так далее с их входами, выходами, именами параметров методов и типами, только без подробных описаний, которые, конечно же, мы должны будем предоставить с помощью аннотаций JSDoc.

  1. Установите Compodoc глобально с помощью npm install -g @compodoc/compodoc.
  2. Создайте файл с именем tsconfig.doc.json, содержащий ключ include, указывающий на папку src.
  3. По желанию вы можете добавить скрипт в файл package.json, который запускает веб-сайт документации:
"scripts": {
  "compodoc": "npx compodoc -p tsconfig.doc.json"
}
Вход в полноэкранный режим Выйти из полноэкранного режима
  1. Теперь запустите его с помощью команды npm run compodoc.

Эта команда создаст папку documentation в корне вашего приложения. Это веб-сайт документации. Он также автоматически откроется в вашем браузере, чтобы вы могли посмотреть, что было создано.

Существует несколько демонстрационных примеров документации, созданных с помощью Compodoc, которые вы можете посмотреть, вот демонстрация документации приложения Angular.

Вы можете дополнительно настроить свой опыт работы с документацией с помощью следующих шагов:

  • Исключить некоторые файлы или типы файлов из документирования, если они вам не нужны.
  • Добавить примеры и описания с помощью аннотаций JSDoc.
  • Просмотреть страницу охвата документации, чтобы узнать, сколько вы уже задокументировали.
  • Возможно, выберите тему и стиль для вашего сайта документации
  • Добавить дополнительные внешние файлы документации
  • Добавить подсветку синтаксиса для примеров кодирования
  • И многое другое

В заключение

Документирование программного обеспечения — это такая же старая практика, как и само написание программного обеспечения. Некоторые команды пропускают эти проекты, но чаще всего это приводит к проблемам в дальнейшем, особенно в растущих командах. Надеюсь, эта статья содержит советы и инструменты для начала документирования ваших проектов и улучшения опыта разработки.

Оцените статью
devanswers.ru
Добавить комментарий