Именование и документирование

Именование в библиотеке Popmotion строится вокруг идеи декларативного описания движения через компактные, семантически точные сущности. Названия функций и параметров отражают не техническую реализацию, а физическую или поведенческую модель анимации. Это формирует стиль API, в котором код читается как описание движения, а не как последовательность императивных команд.

Основу API составляют функции, каждая из которых моделирует отдельный тип движения:

  • tween — интерполяция между двумя состояниями
  • spring — физическая пружина с затуханием
  • physics — движение под действием физических параметров
  • keyframes — последовательность фиксированных состояний во времени
  • decay — затухающее движение с постепенной потерей энергии

Именование этих сущностей не случайно: каждое слово отсылает к модели поведения, а не к способу вычисления. Это позволяет строить код, в котором выбор функции уже описывает характер анимации.

Консистентность параметров и терминологии

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

  • from / to — начальное и конечное значение
  • duration — длительность интервала
  • stiffness — жёсткость пружины
  • damping — коэффициент затухания
  • velocity — начальная скорость
  • mass — масса системы

Единообразие терминов критично: одинаковые физические концепции не переименовываются в разных функциях. Например, скорость всегда обозначается как velocity, независимо от контекста использования.

Именование функций создания анимаций

Фабричный стиль построения API предполагает использование коротких, глагольных названий, отражающих тип создаваемого поведения:

import { tween, spring } from "popmotion";

const fadeIn = tween({
  from: 0,
  to: 1,
  duration: 300
});

Имена функций не содержат лишних префиксов вроде create, поскольку сама библиотека уже является пространством создания motion-объектов. Это снижает шум и повышает плотность семантики.

Композиционные функции и их нейтральные имена

Функции композиции избегают описательных конструкций и используют абстрактные, но устойчивые термины:

  • pipe — последовательное применение трансформаций
  • transform — преобразование значений
  • mix — смешивание значений

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

import { pipe, transform, mix } from "popmotion";

const adjust = pipe(
  transform(v => v * 2),
  mix(0, 100)
);

Именование callbacks и событий

Событийная модель придерживается предсказуемых суффиксов:

  • onUpdate — вызов при каждом обновлении значения
  • onComplete — завершение анимации
  • onStart — начало выполнения
  • onStop — принудительная остановка

Семантика событий строится по принципу «состояние + момент», где имя события фиксирует точку жизненного цикла анимации.

spring({
  from: 0,
  to: 1,
  onUpdate: v => {
    element.style.opacity = v;
  },
  onComplete: () => {
    element.style.opacity = 1;
  }
});

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

Документация API опирается на строгую фиксацию входных и выходных контрактов. Каждый параметр описывается через:

  • тип значения
  • диапазон допустимых значений
  • физическую или логическую интерпретацию
  • влияние на поведение системы

Пример JSDoc-стиля:

/**
 * @param {number} from - начальное значение анимации
 * @param {number} to - конечное значение
 * @param {number} duration - длительность в миллисекундах
 * @param {function} onUpdate - вызывается при каждом тике
 */

Такая структура устраняет неоднозначность и фиксирует поведение без необходимости изучать реализацию.

Типизация как часть документации

В TypeScript-представлении документация и типизация объединяются в единый слой описания API:

type TweenConfig = {
  from: number;
  to: number;
  duration: number;
  onUpdate?: (v: number) => void;
};

Типы выполняют роль формальной документации, уменьшая необходимость дополнительных пояснений в текстовом виде.

Именование внутренних абстракций

Внутренние сущности, не предназначенные для прямого использования, отделяются через соглашения:

  • префикс _ для служебных функций
  • нейтральные технические названия без доменной семантики
  • отсутствие маркетинговых или описательных терминов

Это создаёт границу между публичным API и внутренней реализацией.

Единообразие в обозначении времени и величин

Временные и числовые параметры используют строго фиксированные единицы:

  • время — миллисекунды
  • углы — радианы (внутри вычислений)
  • скорость — единицы на секунду или миллисекунду в зависимости от контекста

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

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

Структура описания функций следует устойчивому порядку:

  • назначение функции
  • входные параметры
  • возвращаемое значение
  • побочные эффекты
  • примеры использования

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

Примеры корректного и некорректного именования

Корректные формы отражают физическую или поведенческую модель:

spring({ stiffness: 200, damping: 20 });
tween({ from: 0, to: 1, duration: 500 });

Некорректные формы нарушают семантическую консистентность:

animateOpacityFast();
doFade();
runMotionThing();

Такие названия теряют связь с моделью движения и разрушают предсказуемость API.

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

Документация рассматривается как формализованное продолжение исходного кода. Описание функций не дублирует реализацию, а фиксирует поведение через:

  • декларацию параметров
  • описание динамики
  • поведенческие сценарии
  • ограничения модели

Такой подход делает API самодостаточным: чтение документации эквивалентно пониманию системы анимации без необходимости анализа исходников.

Оглавление