OpenEuphoria

Re: No one cares?

• Posted by irv Sep 19, 2019
• 1450 views

There seems to be a misunderstanding about documentation:

Here's how it worked when I worked in a large government shop:

Programmer comments each routine to:

1. Indicate what input it expects
2. What it does with that input
3. What output is produced
4. (if neccessary, explain code which does things in an unusual way)

These comments are to remind the programmer, and to inform future maintainers. That's all - no clutter.

Then the testers get the code, and verify (using the programmer's docs) that the routine returns the specified output when fed valid input, and that it handles invalid inputs in a correct manner. (That second part is something programmers don't do very well).

Finally, the doc writers use the program in an actual or simulated real-world situation, and write stand-alone docs in language understandable to the average user. These docs can be as detailed as necessary, illustrated if appropriate, and none of this belongs in the source code!