3 ms·

This seems a lot like cucumber, which is basically a regex expander until it gets down to real code eventually. I have found this style very frustrating when d

This seems a lot like cucumber, which is basically a regex expander until it gets down to real code eventually. I have found this style very frustrating when doing anything complex that's also reused a lot. Particularly because the flow of information (expressed in normal code as variables and arguments) can become very subtle and tightly coupled when it's buried at the very bottom of an expanded expression. Maybe this is a solved problem in the system you're taking about, but I have a really hard time seeing how.

Jtsummers 10y ago
GP talked about this occurring at a defense contractor. The specifications tend(ed) to be much tighter. System X will receive input from this data bus. It will use this wire protocol. It will use that address to push output to <other component>. Messages will be of the following forms. It's often a lot of embedded systems, and the good thing about these is that this level of specification is quite feasible. I've written a "simulator" (not full-blown, it was a stop-gap measure) for a piece of code we're supposed to get from another contractor. My code pretty much started off this way (but LP isn't liked here and it got butchered, started off in org-mode). I had to receive certain messages reading from shared memory (old architecture, can't change it without changing everything else), and respond back with messages stored in other address ranges. So I described the messages, I described the addresses, including references to specifications. My code was, essentially, traceable back to the requirements and specifications documents. In this world we often have an SDD, usually not well developed and unfortunately sometimes made after the fact. Literate programming is a way that you can pair up the design and the code into one place, along with a rationale for the code by way of tying it back to the requirements documents.
EliRivers 10y ago
"This seems a lot like cucumber, which is basically a regex expander until it gets down to real code eventually." It's not at all like that. I must have explained it badly. Cucumber is written for a machine. This was written for humans. Not shown; design discussion, diagrams, links to requirements, pieces of history, and everything else that was helpful for humans to understand the software from requirements to design to implementation.
- stormbrew 10y ago
  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.

Jtsummers 10y ago

GP talked about this occurring at a defense contractor. The specifications tend(ed) to be much tighter. System X will receive input from this data bus. It will use this wire protocol. It will use that address to push output to <other component>. Messages will be of the following forms. It's often a lot of embedded systems, and the good thing about these is that this level of specification is quite feasible. I've written a "simulator" (not full-blown, it was a stop-gap measure) for a piece of code we're supposed to get from another contractor. My code pretty much started off this way (but LP isn't liked here and it got butchered, started off in org-mode). I had to receive certain messages reading from shared memory (old architecture, can't change it without changing everything else), and respond back with messages stored in other address ranges. So I described the messages, I described the addresses, including references to specifications. My code was, essentially, traceable back to the requirements and specifications documents. In this world we often have an SDD, usually not well developed and unfortunately sometimes made after the fact. Literate programming is a way that you can pair up the design and the code into one place, along with a rationale for the code by way of tying it back to the requirements documents.

EliRivers 10y ago

"This seems a lot like cucumber, which is basically a regex expander until it gets down to real code eventually." It's not at all like that. I must have explained it badly. Cucumber is written for a machine. This was written for humans. Not shown; design discussion, diagrams, links to requirements, pieces of history, and everything else that was helpful for humans to understand the software from requirements to design to implementation.

stormbrew 10y ago
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.