4 ms·

Ah, re-reading I think I see where I went wrong. So code is written separately, but cross linked with these document identifiers?

EliRivers 10y ago
Broadly speaking, yes. The programmer might have written something like this: The principal components (message queue, network connector, message handler) are all necessary. They are initialised together, and if any one fails, the program should be aborted. <<Initialise message queue>> <<Initialise network connector>> <<Initialise message handler>> Each initialisation signals success or failure independently, but a global "Error state" object exists; any catastrophic error found will trigger an abort of program with logging. <<Check catastrophic error state>> The message queue feeds itself directly from the network. It needs only be made aware of the connector. This was not done during initialisation for reasons x, y, z. << etc etc >> Somewhere else might be a piece that looks like this: The message queue initialisation is very simple; it's using a library standard queue. See meeting minutes 3452/r for further detail. <<Initialise message queue>>= // ACTUAL CODE The document contains various markup explaining the order of the code, and the order of the human readable sections; upon munging, the human gets a beautiful PDF that intersperses code with design discussion in a good order for the human to read and understand (and consequently review and test, so we've got ourselves a virtuous cycle here), and the machine gets just the code. For the machine, each << XXX >> pieces gets replaced with other << YYY >>, recursively, until it's just code. Because it's munged, there can be a chapter discussing everything there is to know about a single class, for example, and a chapter discussing System Initialisation, or whatever else fits to the needs at hand. If someone wanted to know about initialising the system, they PDF had the broad top-level discussion, and a break down of smaller sections. The reader could then dig into each as deep as they liked, at each stage seeing the design discussion/diagram, and as much of the code detail as they liked. It made working on code I'd never seen before an absolute dream. By the time I reached the actual code, I already knew what it was meant to do and how it worked. On the one hand, a lot of extra work, and it does constrain the coding style you can use; it only makes sense with code that can actually be broken into smaller, meaningful pieces like that. On the other hand, zero bugs found by our customer, the prime contractor. QA and testing and everything else was a massive part, but it all helped. I know the prime contractor was definitely doing some serious testing, because we watched them sue one of the other contractors for general incompetence.

EliRivers 10y ago

Broadly speaking, yes. The programmer might have written something like this: The principal components (message queue, network connector, message handler) are all necessary. They are initialised together, and if any one fails, the program should be aborted. <<Initialise message queue>> <<Initialise network connector>> <<Initialise message handler>> Each initialisation signals success or failure independently, but a global "Error state" object exists; any catastrophic error found will trigger an abort of program with logging. <<Check catastrophic error state>> The message queue feeds itself directly from the network. It needs only be made aware of the connector. This was not done during initialisation for reasons x, y, z. << etc etc >> Somewhere else might be a piece that looks like this: The message queue initialisation is very simple; it's using a library standard queue. See meeting minutes 3452/r for further detail. <<Initialise message queue>>= // ACTUAL CODE The document contains various markup explaining the order of the code, and the order of the human readable sections; upon munging, the human gets a beautiful PDF that intersperses code with design discussion in a good order for the human to read and understand (and consequently review and test, so we've got ourselves a virtuous cycle here), and the machine gets just the code. For the machine, each << XXX >> pieces gets replaced with other << YYY >>, recursively, until it's just code. Because it's munged, there can be a chapter discussing everything there is to know about a single class, for example, and a chapter discussing System Initialisation, or whatever else fits to the needs at hand. If someone wanted to know about initialising the system, they PDF had the broad top-level discussion, and a break down of smaller sections. The reader could then dig into each as deep as they liked, at each stage seeing the design discussion/diagram, and as much of the code detail as they liked. It made working on code I'd never seen before an absolute dream. By the time I reached the actual code, I already knew what it was meant to do and how it worked. On the one hand, a lot of extra work, and it does constrain the coding style you can use; it only makes sense with code that can actually be broken into smaller, meaningful pieces like that. On the other hand, zero bugs found by our customer, the prime contractor. QA and testing and everything else was a massive part, but it all helped. I know the prime contractor was definitely doing some serious testing, because we watched them sue one of the other contractors for general incompetence.