3 ms·
I'm not a big fan of lots of comments in the code itself, but I very much so advocate design documentation. I once had the pleasure of rewriting an Ada avionic
by tjr 17y ago
I'm not a big fan of lots of comments in the code itself, but I very much so advocate design documentation.
I once had the pleasure of rewriting an Ada avionics subsystem in C. The code was very tersely commented, and the only documentation I could find on the subsystem was a requirement to the effect of "such-and-such subsystem shall exist". So I was left to figuring out what the subsystem worked from the code itself.
That's possible to do, but things would have gone a lot faster if I would have had a few pages describing what the goals and overall architecture of the software was.
- aidenn0 17y agoThings only go faster if the design documentation matches the code. This is, in my experience, never. In the best case, the design documentation is updated as the code is written and problems are found. However, even then, decisions made while coding will avoid problems, and ambiguities in the design documentation don't get updated when that happens. I've had to do similar rewrites in the past, and I usually just skim the design documentation to get some idea of what the plan was. However, programming languages are in general the most concise and unambiguous way to represent what a program does.