链接代码结构和架构文档
假设我正在编写一个新的通信协议（本例中我将使用 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
对我来说，这似乎是我在做一些重复性的工作。目前我正在使用正则表达式来加快速度，但是有什么方法可以封装这些数据，以便它可以轻松地显示在文档中，并且还可以轻松地转换为代码？有没有办法将结构与文档分开？
Let's say I am writing a new communication protocol( I'll use TFTP for this example) and in a word document I have the following table(format can vary):
Opcode | 2 bytes
filename | string
padding | 1 byte = 0
mode | string
padding | 1 byte = 0
Now when I go to write the code, I will be making some sort of structure like so:
class TFTP_packet:
short opcode
string Filename
byte padding=0
string mode
byte padding2=0
Which to me seems like I am doing some repetitive work. At the moment I am using regular expressions to speed things up, but is there any way to encapsulate this data so it can be easily displayed in documents, and also easily converted to code? Is there a way to seperate the structures from the document?
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（1）
规范（协议）定义了代码应该做什么；它不应该经常更改，并且无论如何您都不想从源（重新）生成规范，以免代码错误变成规范错误。
CASE 工具试图使详细设计和生成的源代码保持同步，但很少成功。如果你选择那条路，祝你好运。通常，设计文档最初用于开发代码，但成为档案中未维护的历史工件。
另一方面，可以根据需要相对容易地从代码中生成最新的文档——例如 javadoc (java) 或 doxygen (c++) 等。这里的圣杯实际上是对每一个位进行单一来源（没有双关语）内容，并生成最终产品。也就是说，您不想在两个（或更多）地方维护相同的描述、相同的表、相同的数据结构。这并不意味着所有内容都必须记录在一个地方（msword 异或源）：相反，您可能希望将生成的内容（来自源）合并到现有的外部文档（在文档中）。
但是，为了更进一步，我建议不要使用 Word（不灵活、依赖于平台、难以自动化），而是使用 OpenOffice (LibreOffice)“主”文档 (
*.odm），引入并合并常规文档 (*.odt) 和生成的图像和图像。文本片段（从源代码甚至测试程序输入/输出生成）。构建生成的文档可以编写脚本（包括 pdf 生成），甚至可以合并到整个源代码构建过程中。A specification (the protocol) defines what the code should do; it should not change frequently, and you wouldn't want to (re-)generate the spec from the source anyway, lest code bugs become specification bugs.
CASE tools try to keep detailed designs and generated source in sync, but rarely succeed. Good luck with that if you choose that path. Usually a design doc is used to initially develop the code, but becomes an unmaintained historical artifact for the archives.
On the other hand, up-to-date documentation can relatively easily be generated from code as often as needed -- e.g. javadoc (java) or doxygen (c++), etc. The holy grail here really is to single-source every single bit (no pun intended) of content, and generate the final product. That is, you don't want to maintain the same description, same table, same data structure in two (or more) places. That doesn't mean everything has to be documented in one place (the msword XOR the source): rather, you'll likely want to merge your generated content (from the source) into existing external documentation (in documents).
But, just to take this a step further, I would recommend that rather than using Word (inflexible, platform dependent, hard to automate), instead use OpenOffice (LibreOffice) "master" documents (
*.odm) that pull in and merge regular documentation (*.odt) and generated images & text fragments (generated from your source code or even test program input/output). Building the resulting documentation can be scripted (including pdf generation) or even incorporated into your overall source code build process.