Linking code structures and architecture documentation

Question

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?

Have you considered using a CASE solution such as Visio or Dia rather than a Word document? — Brian Driscoll, Mar 25 '11 at 17:27

score 0 · Answer 1 · answered Jun 07 '12 at 08:28

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.

Linking code structures and architecture documentation

1 Answers1