链接代码结构和架构文档答案

【问题标题】：Linking code structures and architecture documentation链接代码结构和架构文档
【发布时间】：2011-03-25 17:05:59
【问题描述】：

假设我正在编写一个新的通信协议（我将在此示例中使用 TFTP）并且在 word 文档中我有下表（格式可以变化）：

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

这对我来说似乎是在做一些重复性的工作。目前我正在使用正则表达式来加快速度，但是有没有办法封装这些数据，以便它可以轻松地显示在文档中，也可以轻松地转换为代码？有没有办法将结构与文档分开？

【问题讨论】：

您是否考虑过使用 Visio 或 Dia 等 CASE 解决方案而不是 Word 文档？

标签： document-management

【解决方案1】：

规范（协议）定义了代码应该做什么；它不应该经常更改，并且无论如何您都不想（重新）从源代码生成规范，以免代码错误成为规范错误。

CASE 工具试图使详细设计和生成的源代码保持同步，但很少成功。如果你选择那条路，祝你好运。通常，设计文档用于最初开发代码，但成为档案中无人维护的历史文物。

另一方面，可以根据需要从代码中相对轻松地生成最新的文档——例如javadoc (java) 或 doxygen (c++) 等。这里的圣杯实际上是对内容的每一位（没有双关语）进行单一来源，并生成最终产品。也就是说，您不想在两个（或更多）地方维护相同的描述、相同的表、相同的数据结构。这并不意味着所有内容都必须记录在一个地方（msword XOR the source）：相反，您可能希望将生成的内容（来自源）合并到现有的外部文档（在文档中）。

但是，为了更进一步，我建议不要使用 Word（不灵活、依赖平台、难以自动化），而是使用 OpenOffice (LibreOffice) “主”文档 (*.odm)并合并常规文档 (*.odt) 和生成的图像和文本片段（从您的源代码甚至测试程序输入/输出生成）。可以编写生成的文档（包括生成 pdf），甚至可以将其合并到您的整个源代码构建过程中。

【讨论】：