Описание набора параметров

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

Авторы технических документов часто оказываются перед необходимостью описать набор параметров, передаваемых системе или какому-то из ее компонентов. Сложно представить себе руководство программиста, в котором ни разу не встретилось бы описание набора аргументов, а спецификация микросервиса наверняка будет содержать структуры многочисленных DTO.

Удобный и компактный способ описания параметров — таблица. Типичный состав колонок такой таблицы приведен ниже.

Колонка	Содержание
Имя/позиция	Имя параметра или номер его позиции в списке
Тип	Тип данных, к которому относится значение параметра
Значение	Содержание параметра: что выражает значение параметра, как оно интерпретируется системой
Пример	Пример значения
По умолчанию	Значение, которое система будет считать присвоенным параметру, если это не сделано явно. Если значение параметра должно быть указано явно, то об этом делают специальную пометку

Предположим, мы намерены описать набор свойств объекта JSON следующего вида.

{
    "ticketNumber": "ABC12345",
    "screeningDateTime": "2024-08-12 21:00",
    "rowNo": 10,
    "seatNo": 22,
    "usedFlag": false,
    "setOfPrivileges": "vip"
}

Пример табличного описания набора свойств JSON-объекта с такой структурой приведен ниже.

Свойство	Тип	Значение	Пример	По умолчанию
ticketNumber	String	Уникальный номер билета	ABC12345	Обяз.
screeningDateTime	Время киносеанса	Дата и время начала киносеанса в часовом поясе кинотеатра	2024-08-12 21:00	Обяз.
rowNo	Number	Номер ряда	10	Обяз.
seatNo	Number	Номер места в ряду	22	Обяз.
usedFlag	Boolean	Флаг, означающий, что билет уже был использован	false	Обяз.
setOfPrivileges	Набор привилегий	Набор привилегий, предоставленных зрителю	vip	regular

Во многих случаях значения параметров должны подчиняться определенным ограничениям: возраст всегда неотрицательный, дата должна быть представлена в конкретном формате и т. п. Описания подобных ограничений, собранные в один раздел, могут выглядеть слишком громоздко. Кроме того, значения, подчиняющиеся одним и тем же ограничениям, могут фигурировать в разных контекстах. Целесообразно расценивать такие значения как принадлежаще специализированным типам данных и описывать их в самостоятельных разделах. Например, в приведенном примере параметр privileges принимает значения типа «Набор привилегий». Какие именно ограничения он накладывает на значения параметра (например, значением параметра может быть одна из трех строк: vip, preferential или regular), следует описать в разделе, посвященном этому типу данных.

См. Описание типа данных.

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

• объект или структура определенного вида;
• массив атомарных значений;
• массив объектов или структур определенного вида.

См. Описание структуры данных.