Документация компонентов: свойства, примеры и условия применения

Прямой ответ

Документация компонента содержит описание свойства с типом, рабочий пример и условие применения варианта, поэтому настройка выполняется без чтения кода.

/** @param {boolean} disabled — отключает действие */

Описание сопровождает код, поэтому изменение свойства сопровождается обновлением описания. О примерах состояний — в статье про Storybook.

Описание свойств и типы значений

Свойство описывается типом и назначением, поэтому допустимые значения определены до применения компонента.

Тип свойства. Ограничивает значения, поэтому передача значения другого типа обнаруживается до отображения.

Назначение. Описывает, что изменяет параметр, поэтому выбор свойства не требует чтения кода компонента.

Значение по умолчанию. Показывает поведение без передачи свойства, поэтому отсутствие параметра не приводит к неопределённому состоянию.

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

Отдельный аспект — обязательность свойства. Свойство, без которого компонент не отображается корректно, отмечается как обязательное, поэтому отсутствие значения обнаруживается до применения.

Рабочие примеры и условие применения

Пример показывает поведение компонента, поэтому условие применения определяет, в какой ситуации используется вариант.

Рабочий пример. Отображается и выполняется, поэтому поведение проверяется до применения в продукте.

Условие применения. Описывает ситуацию, в которой вариант уместен, поэтому выбор между вариантами определяется правилом.

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

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

Обновление описания вместе с кодом

Описание обновляется при изменении свойства, поэтому расхождение между кодом и документацией не накапливается.

Изменение свойства. Добавление либо удаление параметра сопровождается обновлением описания, поэтому перечень свойств соответствует коду.

Изменение поведения. Изменение поведения без изменения свойства отражается в описании, поэтому ожидание потребителя соответствует реализации.

Проверка соответствия. Описание проверяется вместе с кодом, поэтому устаревшее описание обнаруживается до выпуска.

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

О требованиях к компонентам — в статье про доступность библиотеки; о структуре системы — в статье про дизайн‑систему.

Состав описания при изменении библиотеки

Состав описания обновляется при изменении библиотеки, поэтому перечень свойств соответствует реализации.

Новый компонент. Добавление компонента сопровождается описанием свойств и примером, поэтому настройка выполняется по документации.

Новое свойство. Добавление свойства сопровождается описанием типа и назначения, поэтому допустимые значения определены.

Удаление свойства. Удаление отражается в описании и отмечается в версии, поэтому потребитель знает объём правки.

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

Практика: ведение документации компонента

1. Описывайте тип каждого свойства. Передача недопустимого значения обнаруживается до отображения.

2. Указывайте назначение свойства. Настройка компонента не требует чтения кода.

3. Отмечайте обязательные свойства. Отсутствие значения обнаруживается до применения.

4. Фиксируйте значение по умолчанию. Поведение без передачи свойства определено.

5. Добавляйте рабочий пример на каждое состояние. Поведение проверяется до применения в продукте.

6. Описывайте условие применения варианта. Выбор между вариантами определяется правилом.

7. Обновляйте описание вместе с изменением кода. Перечень свойств соответствует реализации.

Рекомендации:

1. Не описывайте свойства без типа. Допустимые значения не определены, поэтому поведение при недопустимом значении не определено.
2. Не перечисляйте варианты без условия применения. Выбор между подходящими вариантами принимается на месте.
3. Не обновляйте описание отдельно от кода. Перечень свойств отстаёт от реализации.
4. Проверяйте соответствие описания коду при выпуске. Устаревшее описание обнаруживается до применения потребителем.
5. Пересматриваем примеры при добавлении свойства. Новое состояние требует отдельного примера.

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

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

1. Диагностика. Проверка описания показала, что свойство было описано без типа и без значения по умолчанию. Перечень свойств содержал только имена, поэтому допустимые значения определялись по коду компонента, а поведение при недопустимом значении не было описано.
2. Причина. Описание свойств создавалось по именам параметров без указания типа, назначения и значения по умолчанию, поэтому потребитель настраивал компонент по неполному перечню.
3. Действия. (а) Добавили тип к каждому свойству, чтобы допустимые значения были определены; (б) описали назначение каждого свойства, чтобы настройка не требовала чтения кода; (в) зафиксировали значения по умолчанию, чтобы поведение без передачи свойства было определено; (г) отметили обязательные свойства, чтобы отсутствие значения обнаруживалось до применения; (д) добавили рабочие примеры для каждого состояния и установили правило обновления описания вместе с изменением кода.
4. Результат. Допустимые значения свойств определены описанием, поэтому настройка компонента выполняется по документации без чтения кода.

Вывод: описание свойств без типа и значения по умолчанию требует чтения кода компонента, поэтому настройка замедляется, а недопустимое значение обнаруживается при отображении. Тип, назначение, значение по умолчанию и рабочий пример делают описание достаточным для настройки.

FAQ

Что описывать для свойства компонента? Тип, назначение, обязательность и значение по умолчанию. Настройка выполняется по описанию без чтения кода.

Зачем описывать условие применения варианта? Выбор между подходящими вариантами определяется правилом. Без условия решение принимается на месте и расходится между экранами.

Почему пример должен быть рабочим? Поведение проверяется до применения в продукте. Описание без примера не показывает результат настройки.

Как поддерживать описание в соответствии с кодом? Обновлением описания вместе с изменением свойства и проверкой соответствия при выпуске версии.

Источники: Storybook Writing Docs, JSDoc, Semantic Versioning — ссылки в шапке.