There ought to be plenty of documentation for EVERY line of code.

That's why coding and debugging are, at most, 5% of the workload associated with good firmware. For each line of code there should not only be an explanation of EXACTLY what that line is supposed to accomplish, but also how it is supported/warranted in the requirements documentation, which, BTW, should be written, examined, and critically reviewed before the hardware/firmware design is even begun.

Code written in a HLL should be written BEFORE the processor is selected, and before the hardware is designed, and modifications only made in order to support higher-reliability or lower-cost hardware. Naturally, some additional code will be needed, probably in ASM in order to accomodate the specifics of the processor.

RE