Правила разработки

Документ устанавливает обязательные правила, по которым устроены части платформы O.G.A.S., по которым платформа ведёт себя по отношению к человеку и по которым ведутся разработка и документация. Правила действуют для всех частей платформы, для средств разработки и для документации.

1 Общие положения

1.1 Назначение правил

1.1.1 Правила обеспечивают три свойства платформы:

• любую часть можно изменить, добавить или удалить, не переделывая остальные части;
• ошибку можно найти и исправить в одном месте;
• поведение платформы можно настроить без изменения кода.

1.1.2 Правило, которое не служит ни одному из этих свойств, в документ не включается.

1.2 Область применения

1.2.1 Правила действуют для следующих частей:

• ядро;
• общий код протокола;
• функции платформы;
• модули и общий код модулей (OGAS SDK);
• мастерская;
• средства разработки: сборка, проверки, скрипты;
• документация.

1.3 Термины и определения

1.3.1 В документе применяют термины, приведённые в таблице 1. Остальные термины — по Термины.

Таблица 1 — Термины правил

1.4 Порядок применения

1.4.1 Все правила обязательны. Степень обязательности выражается тремя формулировками:

• «должен» — обязательное требование;
• «не допускается» — запрет;
• «допускается» — разрешение при названном в той же фразе условии.

Других формулировок обязательности («желательно», «по возможности», «как правило») в правилах нет.

1.4.2 Запрет действует одновременно для кода, документации и интерфейса, если в правиле не указано иное.

1.4.3 Каждое правило содержит перечень признаков нарушения. Соответствие проверяют по этому перечню: хотя бы один признак означает нарушение.

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

1.4.5 Нарушение, которое не устранено сразу, записывают в перечень несоответствий.

1.4.6 Документ части может дополнять эти правила и не может им противоречить. При противоречии исправляют документ части.

1.4.7 На правило ссылаются по номеру подраздела: «правило 2.6».

2 Требования к устройству частей

2.1 Разделение на составляющие

2.1.1 Часть должна быть разделена на составляющие так, чтобы у каждой составляющей была одна задача. Задача описывается одним предложением; если в описании союз «и» соединяет разные действия, это две задачи.

2.1.2 Задача без подзадач выполняется в одном файле. Задача с подзадачами выполняется в папке: в ней главный файл и по файлу на подзадачу. Глубина вложенности должна повторять устройство задачи и не должна превышать его.

2.1.3 Главный файл части (main.rs, main.py, app.js) должен только запускать часть, принимать сообщения и передавать каждое составляющей, чья это задача. В главном файле не допускаются расчёт, проверка, хранение данных и объявление состояния службы.

2.1.4 Делить составляющие следует по задачам, а не по объёму. Не допускается делить файл только потому, что он длинный, и не допускается заводить файл, у которого нет своей задачи.

2.1.5 Имя составляющей должно называть её задачу. Связанные составляющие должны лежать рядом, несвязанные — в разных местах.

2.1.6 Признаки нарушения:

• главный файл выполняет работу задачи или объявляет структуру состояния службы;
• в одном файле выполняются разные задачи, например обработка запросов, расчёт и описание настроек;
• чтобы изменить одну задачу, требуется читать код других задач;
• нужное место в файле находят только поиском, а не по названию раздела;
• чтобы проследить один сценарий, требуется открыть несколько файлов, каждый из которых только передаёт работу дальше.

2.2 Значения и тексты вне кода

2.2.1 Всё, что может потребоваться изменить, должно изменяться без правки кода. Значения и тексты хранятся в отдельных файлах, код получает их оттуда.

2.2.2 Значение относится к одному из трёх видов. Место объявления и порядок изменения каждого вида приведены в таблице 2.

Таблица 2 — Виды значений

2.2.3 Вид значения определяют вопросом: будет ли повод изменить его у кого-либо, кроме исполнителя? Если да, значение является настройкой. Если нет, значение является внутренней величиной и объявляется с именем в файле констант.

2.2.4 Тексты для человека (подписи, названия и подсказки настроек, сообщения об ошибках) должны храниться в словарях хозяина: locales/ru.json и locales/en.json. Код и схема настроек содержат только ключ текста.

2.2.5 Служебный текст (запись журнала ядра, вывод командной строки, пояснение для разработчика внутри ошибки) пишется в коде на английском языке и в словари не выносится.

2.2.6 Код должен получать настройку через хозяина настроек, текст — через словарь, константу — по имени из файла констант. Собственные умолчания, пределы и запасные тексты в коде не допускаются.

2.2.7 Если хозяин настроек недоступен, код берёт умолчание и пределы из той же схемы настроек через общий помощник. Вторая копия умолчания не допускается.

2.2.8 Признаки нарушения:

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

2.3 Взаимодействие частей только через договор

2.3.1 Части должны взаимодействовать только через договор. Не допускается читать файлы другой части, подключать её код, записывать в её документы и пользоваться её внутренними данными.

2.3.2 Метод, поле или событие, которых нет в описании договора, являются нарушением, даже если код работает.

2.3.3 Зависимость части от другой части должна быть объявлена в описании части; у функции платформы — в поле requires файла function.json. Скрытые зависимости не допускаются.

2.3.4 Если часть недоступна, остальные части должны продолжать работу и показывать человеку, чего не хватает.

2.3.5 Отказавшая часть должна сообщать об отказе ошибкой с кодом, местом отказа и признаком, поможет ли повтор. Отказ одной части не должен останавливать другие.

2.3.6 Признаки нарушения:

• изменение внутри одной части требует изменения другой, хотя договор между ними не менялся;
• удаление или отключение модуля или функции останавливает платформу вместо понятного сообщения;
• часть читает файл или внутренние данные другой части напрямую;
• часть узнаёт об отказе другой части по зависанию или падению;
• часть пользуется договором другой части, не объявив зависимость от неё.

2.4 Единственный хозяин

2.4.1 У каждого документа, настройки, значения и действия должен быть ровно один хозяин. Только хозяин записывает и только хозяин отвечает за смысл; остальные обращаются к нему.

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

2.4.3 Изображение на экране, кэш и значение в памяти являются копиями. Тот, кто держит копию, после своего изменения перечитывает значение у хозяина.

2.4.4 Проверку перед изменением выполняет хозяин в момент изменения, а не держатель копии.

2.4.5 Префикс имени называет хозяина: ключ graph.runs_keep принадлежит функции графа, метод core.status — ядру.

2.4.6 Признаки нарушения:

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

2.5 Расширение через готовое место

2.5.1 Основа части — то, на чём часть держится: цикл ядра, формат сообщения, уровни настроек, области мастерской. Новая возможность должна добавляться в основу как ещё один элемент готового места: функция — в реестр, ключ — в схему настроек, вид узла — в набор видов, окно — в мастерскую.

2.5.2 Изменение основы (новый канал обмена, новая область мастерской, новый уровень настроек) допускается только решением, записанным в журнале решений.

2.5.3 Действие должно выполняться той частью, к предмету которой оно относится. Узел графа не управляет платформой; окно мастерской не изменяет пределы ядра.

2.5.4 Признаки нарушения:

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

2.6 Отсутствие в части сведений о других частях

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

2.6.2 В коде части допускаются сведения о другой части только одного рода — договор этой части: имена её методов и событий, форматы её документов, её константы договора. Это допускается, только если зависимость от этой части объявлена (2.3.3).

2.6.3 У ядра нет зависимостей ни от одной части. Поэтому в коде ядра сведений о других частях нет совсем: всё, что ядро делает для частей, определяется реестром функций и описаниями функций.

2.6.4 В коде части не допускаются:

• имена других частей и их элементов;
• понятия предметной области другой части. Например, для ядра — «процесс», «прогон», «модуль», «окно»;
• значения, умолчания и пределы, хозяином которых является другая часть;
• ключи настроек и тексты словарей другой части;
• выбор поведения по имени части, элемента, процесса или окна.

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

2.6.5 Если частям нужно разное поведение, различие должно выражаться признаком, который каждая часть объявляет о себе. Код читает признак, а не имя. Пример: ядро запускает мастерскую не потому, что знает функцию ui, а потому, что в описании функции объявлен признак interactive.

2.6.6 Настройка другой части не является её договором. Если части нужно значение, хозяином которого является другая часть, она получает его вызовом метода или событием хозяина.

2.6.7 Примеры нарушения и правильного устройства:

• Нарушение: ядро разбирает флаг командной строки --process и знает, что глагол demo требует процесс. Понятие «процесс» принадлежит функции графа. Правильно: глагол, вызываемый метод и аргументы описаны в реестре функций; ядро подставляет значения аргументов в вызов, не зная их смысла.
• Нарушение: функция модулей читает настройку i18n.language, хозяином которой является функция языков. Правильно: язык сообщает его хозяин методом или событием.

2.6.8 Признаки нарушения:

• в коде части есть сравнение с именем конкретной части, элемента, процесса или окна;
• в коде части есть понятие, значение, умолчание или ключ настройки, хозяином которых является другая часть;
• добавление, изменение или удаление части требует правки кода другой части, хотя договор между ними не менялся;
• поведение, которое нельзя получить для новой части без изменения кода;
• часть пользуется договором другой части, не объявив зависимость от неё.

2.7 Наблюдаемость

2.7.1 Всё, что влияет на результат, должно быть названо явно: правило слияния входов, цикл, повтор, уровень настройки, отметка «Хранить».

2.7.2 Команда изменяет состояние, запрос только читает, событие сообщает о том, что уже произошло. Запрос, который что-либо изменяет, является нарушением.

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

2.7.4 Отказ фоновой работы (работы, которую никто не ждёт ответом) должен сообщаться событием, а если событие отправить нельзя — выводом в поток ошибок, который сохраняет ядро.

2.7.5 Признаки нарушения:

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

2.8 Отсутствие лишнего

2.8.1 Не допускается заводить слой, библиотеку, канал, обёртку или признак ради одного случая или впрок. Механизм допускается, если у него есть два пользователя, либо второй пользователь записан в техническом задании или в журнале решений.

2.8.2 Новую внешнюю зависимость допускается заводить только с записанной причиной.

2.8.3 Правило 2.2 этому не противоречит: настройка не является лишним механизмом, это законное место значения.

2.8.4 Признаки нарушения:

• механизм с одним пользователем, у которого второй нигде не записан;
• внешняя зависимость, причина которой не записана.

2.9 Единообразие

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

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

2.9.3 Признаки нарушения:

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

2.10 Самодостаточность элемента

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

2.10.2 Изменение элемента выполняется в одной папке и не затрагивает ни другие элементы, ни систему, в которой элемент работает.

2.10.3 Добавление элемента — это добавление его папки, удаление — удаление папки. Остальные элементы продолжают работать.

2.10.4 Снаружи папки допускается только запись в готовом месте, и только если её нельзя вывести из папки элемента.

2.10.5 Система, в которой работают элементы, описывает в документации свой механизм, а не каждый элемент. Общее для многих элементов (цикл, который их вызывает, договор, по которому с ними говорят) принадлежит системе и в элементы не копируется.

2.10.6 Признаки нарушения:

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

2.11 Независимость платформы от документации

2.11.1 Документация описывает платформу; платформа о документации не знает. В коде частей, словарях, текстах интерфейса, сообщениях, записях журналов, именах и описаниях проверок не допускаются ссылки на документы, их разделы, номера правил и шифры требований. Допускается одно: пункт «Справка» открывает документацию на сайте платформы, ogas.space, целиком, без раздела.

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

2.11.3 Средствам разработки (проверкам в make ci) допускается читать документацию, чтобы сверить код с описанным договором. Средства разработки в поставку не входят.

2.11.4 Документация разработчиков в поставку не входит; документация для людей читается на сайте платформы.

2.11.5 Признаки нарушения:

• в коде части, словаре или сообщении есть имя файла документации, путь docs/, знак раздела «§», номер правила, обозначение документа или шифр требования;
• поведение части зависит от содержимого документации;
• поставка содержит документацию или ссылается на неё.

3 Требования к поведению платформы по отношению к человеку

3.1 Действия только с ведома человека

3.1.1 Платформа не должна выполнять действия, о которых человек не просил и о которых он не узнает.

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

3.1.3 Данные человека удаляются только по его прямой просьбе или по правилу, которое человек видит и может настроить. Пример такого правила — уборка старых прогонов по настройке graph.runs_keep.

3.1.4 Переполнение, обрыв и отказ должны заканчиваться видимой ошибкой, а не потерей данных.

3.1.5 Платформа не останавливается и не отбрасывает несохранённые изменения, не спросив человека.

3.1.6 Платформа не отправляет данные за пределы компьютера по своей инициативе.

3.1.7 Признаки нарушения:

• установка, удаление или отправка данных произошли без команды человека и без видимого ему правила;
• данные пропали без сообщения об ошибке;
• несохранённые изменения отброшены без вопроса.

3.2 Явный отказ

3.2.1 Если платформа не может выполнить просьбу, она должна отказать и сообщить код ошибки, текст для человека, место отказа и признак, поможет ли повтор.

3.2.2 Незнакомое не читается как знакомое. Документ более новой версии, путь за пределы разрешённой папки, неизвестный формат вызывают отказ, а не попытку угадать.

3.2.3 Отказ не оставляет частично выполненной работы: записанное возвращают в прежнее состояние или явно помечают как неполное.

3.2.4 Признаки нарушения:

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

3.3 Отсутствие ложных обещаний

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

3.3.2 Быстродействие и пределы называют только по результатам измерения с указанием машины и даты.

3.3.3 Внешние действия модуля (письма, файлы, запросы в сеть) платформа не отменяет и прямо сообщает об этом.

3.3.4 Признаки нарушения:

• интерфейс показывает кнопку, которая ничего не делает;
• названо число быстродействия без измерения;
• обещана отмена действия, которую платформа выполнить не может.

3.4 Понятный язык интерфейса

3.4.1 Всё, что видит человек, должно быть написано общеупотребительными словами. Человек, умеющий пользоваться программами, не обязан знать термины платформы.

3.4.2 Требование относится к мастерской, названиям и пояснениям настроек, сообщениям об ошибках и словарям модулей.

3.4.3 Термин допускается только в подробностях и только рядом с пояснением.

3.4.4 Подсказка сообщает, что произойдёт, а не как это устроено внутри. Сообщение об ошибке сообщает, что случилось и что делать.

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

3.4.6 Вывод командной строки является средством разработки и диагностики; требования 3.4.1–3.4.5 на него не распространяются.

3.4.7 Признаки нарушения:

• текст интерфейса содержит термин без пояснения;
• сообщение об ошибке не говорит, что делать;
• текст есть только на одном языке.

3.5 Сохранность записанного при сбое

3.5.1 Документ должен записываться целиком или не записываться совсем: прежняя целая версия сохраняется при обрыве записи.

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

3.5.3 Признаки нарушения:

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

4 Порядок разработки

4.1 Последовательность от общего к частному

4.1.1 Разработка идёт по уровням: назначение и требования → устройство платформы в целом (Устройство платформы) → устройство частей (Программа: граф и запуски — Защита) → договоры и форматы (Обмен с ядром, Форматы файлов).

4.1.2 Следующий уровень не обсуждают и не реализуют, пока не согласован предыдущий.

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

4.1.4 Реализацию выполняют в том же порядке: сначала то, на чём держится целое, затем частности.

4.2 Запись решений

4.2.1 Каждое решение должно быть записано в журнале решений с причиной. Решение без причины нельзя пересмотреть обоснованно. Журнал ведётся вне документации (5.1.4).

4.2.2 Решение, которое меняет описание продукта, одновременно вносят в документ, который оно меняет. Запись в журнале без изменения документа и изменение документа без записи в журнале являются нарушением.

4.2.3 Решения о продукте (что платформа делает для человека) принимает владелец продукта. Технические решения в пределах уже принятых решений о продукте принимает исполнитель и записывает их с причиной.

4.2.4 Пересмотренное решение не удаляют: прежнее и новое записывают рядом в разделе пересмотренных решений журнала.

4.3 Приоритет документации над кодом

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

4.3.2 Если код расходится с документацией, исправляют код. До исправления расхождение записано в перечне несоответствий. После исправления запись удаляют.

4.3.3 Документацию изменяют только решением (4.2). Не допускается изменять документацию потому, что код уже сделан иначе.

4.4 Открытые вопросы

4.4.1 Вопрос без решения должен быть записан в перечне открытых вопросов вместе с предложением исполнителя. Не допускается закрывать вопрос кодом по принципу «пока так».

4.4.2 Решённый вопрос удаляют из перечня, а решение записывают по 4.2.

4.5 Подтверждение готовности проверкой

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

4.5.2 Каждую новую автоматическую проверку один раз запускают на заведомо испорченном коде и убеждаются, что она не проходит. Проверка, которая не может не пройти, проверкой не считается.

4.5.3 Непроверенное называют непроверенным в отчёте и в перечне несоответствий.

4.5.4 Ручную проверку записывают со сборкой, машиной, датой и результатом.

4.5.5 Правило, соблюдение которого может проверить программа, должна проверять программа в make ci.

4.6 Порядок проработки механизма и восприятия

4.6.1 Части платформы делятся на два рода, и порядок работы у них разный.

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

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

4.6.4 Часть относят к механизму, если её ошибку нельзя исправить, не испортив уже сделанное людьми.

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

4.7 Контрольные вопросы перед добавлением нового

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

1) кто хозяин и кто не имеет права это изменять (правило 2.4); 2) в какое готовое место это встаёт (правило 2.5); 3) какие значения в нём настраиваются и какие тексты увидит человек (правила 2.2 и 3.4); 4) через какой договор с ним взаимодействуют другие части и какие зависимости объявлены (правила 2.3 и 2.6); 5) не возникает ли выбор поведения по имени и какой признак его заменит (правило 2.6).

4.7.2 Если нет ответа хотя бы на один вопрос, код не пишут, а вопрос записывают по 4.4.

5 Требования к документации

5.1 Назначение и состав

5.1.1 Документация описывает платформу такой, какая она есть: что она делает, как ею пользоваться, как она устроена и как её расширять. Код приводится в соответствие с ней (4.3).

5.1.2 Состав документации — карта docs/README.md: каждый документ на ней назван со ссылкой и тем, кому он нужен. Документ, которого нет на карте, не является частью документации; новый документ вносят на карту вместе с его созданием.

5.1.3 Документы разложены по читателям: guide/ — тому, кто собирает программы; reference/ — справочник; sdk/ — автору модулей и сценариев; platform/ и contract/ — тому, кто разбирается в устройстве платформы.

5.1.4 Решения с их причинами, открытые вопросы, несоответствия кода документации, исследования и замеры ведутся вне документации. Документация пересказывает только то, что из них стало устройством платформы.

5.1.5 Английский перевод документации лежит в docs/en/ со своей картой docs/en/README.md. У переведённого документа те же нумерованные разделы, что у русского, и правят их вместе: make ci сверяет разделы перевода с оригиналом, проверяет его ссылки, а перечни настроек, кодов ошибок, видов узлов и имён SDK в нём — по коду.

5.2 Содержание

5.2.1 Документ описывает только нынешнюю платформу. Не допускаются даты, ссылки на решения и на то, кто их принял, рассказы о том, как было раньше и что будет потом. Причина «почему так» излагается по существу, как свойство устройства.

5.2.2 Каждый факт записан в одном документе. Другие документы ссылаются на него и не повторяют его.

5.3 Структура

5.3.1 Документ начинается с заголовка «# Название» и короткого вступления: о чём документ и кому он нужен.

5.3.2 Разделы, подразделы и пункты нумеруют арабскими цифрами: «1», «1.1», «1.1.1»; после номера точку не ставят. Справочные материалы, которые не нужны для понимания основного текста, выносят в приложения: «Приложение А».

5.3.3 Таблицу снабжают заголовком над ней: «Таблица 3 — Наименование»; нумерация таблиц сквозная в пределах документа.

5.4 Язык и оформление

5.4.1 Документы пишут простым и точным русским языком: одна мысль — один абзац, сперва главное, потом подробности. Слово из кода объясняют словами при первом появлении. Английский перевод пишут по тому же правилу по-английски.

5.4.2 Требования к коду формулируют словами «должен», «не допускается», «допускается» (1.4.1).

5.4.3 Термины применяют в значениях из Термины. Один термин обозначает одно понятие; новый термин вносят туда до его первого применения.

5.4.4 Имена из кода, форматов, методов и ключей пишут моноширинным шрифтом так, как они записаны в коде. Кавычки — «ёлочки»; тире между словами — длинное, с пробелами.

5.5 Ссылки

5.5.1 На другой документ ссылаются его названием со ссылкой на файл и номером раздела: «(Программа: граф и запуски, 12.1)».

5.5.2 Внутри документа ссылаются на номер: «(см. 5.1)», «(таблица 3)», «(приложение А)».

5.6 Признаки нарушения требований к документации

5.6.1 Признаки нарушения:

• документа нет на карте или на карте есть документ, которого нет;
• у документа нет заголовка или нумерации разделов;
• в документе есть дата, ссылка на решение или рассказ о прошлом и будущем;
• один факт записан в двух документах;
• ссылка указывает на несуществующий документ или раздел;
• термин применён в значении, отличном от Термины;
• требование сформулировано иначе, чем в 1.4.1.

Приложение А (справочное). Применение правил в частях

Таблица А.1 — Примеры применения правил