Связывание структур кода и документации по архитектуре - PullRequest
Новая
       23

Связывание структур кода и документации по архитектуре

1 голос
/ 25 марта 2011

Допустим, я пишу новый протокол связи (я буду использовать TFTP для этого примера), и в текстовом документе у меня есть следующая таблица (формат может отличаться): 

Opcode   |  2 bytes
filename | string
padding  | 1 byte = 0
mode     | string
padding  | 1 byte = 0

Теперь, когда яиди, чтобы написать код, я сделаю какую-то структуру вроде: 

class TFTP_packet:
    short opcode
    string Filename
    byte   padding=0
    string mode
    byte   padding2=0

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

1 Ответ

0 голосов
/ 07 июня 2012

Спецификация (протокол) определяет, что должен делать код; он не должен часто меняться, и вы все равно не захотите (повторно) генерировать спецификацию из источника, чтобы ошибки кода не стали ошибками спецификации.

Инструменты CASE пытаются синхронизировать подробные проекты и сгенерированный источник, но редко достигают успеха. Удачи с этим, если вы выберете этот путь. Обычно проектная документация используется для первоначальной разработки кода, но становится неподдерживаемым историческим артефактом для архивов.

С другой стороны, актуальная документация может относительно легко генерироваться из кода так часто, как это необходимо - например, javadoc (java) или doxygen (c ++) и т. д. Святой Грааль здесь на самом деле заключается в том, чтобы получать из каждого бита (без каламбура) единый источник контента и генерировать конечный продукт. То есть вы не хотите поддерживать одно и то же описание, одну и ту же таблицу, одну и ту же структуру данных в двух (или более) местах. Это не означает, что все должно быть задокументировано в одном месте (msword XOR источник): скорее всего, вы захотите объединить сгенерированный контент (из источника) в существующую внешнюю документацию (в документах).

Но, просто чтобы сделать этот шаг дальше, я бы порекомендовал вместо того, чтобы использовать Word (негибкий, зависимый от платформы, сложный для автоматизации), вместо этого использовать OpenOffice (LibreOffice) «главные» документы (*.odm), которые извлекают и объединять обычную документацию (*.odt) и сгенерированные изображения и фрагменты текста (сгенерированные из вашего исходного кода или даже ввода / вывода тестовой программы). Построение итоговой документации может быть выполнено по сценарию (включая генерацию PDF) или даже включено в общий процесс сборки исходного кода.

...