Ftn I/Os documentation best practices

What programming language are you using? If your answer is "C", it's wrong.

If you are just putting these things in comments, then they will get out of sync with the code. The best you can do is writing something like a Python script that will read the C code and check for the pattern of comments.

If you want something really useful, you need a programming language that will let you write the contracts in the language itself - then they can be checked and enforced. Ada, D, and Scala are examples. C++ has a Boost.Contracts library, and language support for contracts is due in C++23 (last I heard - but it might be delayed again).

I'd have to agree. I've worked with many projects and third-party libraries over the decades which had a big template of comments for every function which described the input/ouput parameters, return value, global variables used, and so on.

Often these templates generated documents by using something like Doxygen.

And on _every_single_one_ of those projects and libraries, the comments were wrong often enough that nobody who knew which way was up paid any attention to them. If you wanted to know what the parameters were for, what the function returned, and so on, you read the C code.

A lot of the time, even the numbers and names of the parmeters described in the template didn't match the code.

The auto-generated PDF documents and HTML web site looked nice, though.

Accuracy of such in-code documentation varies, but there is generally no way to check it automatically. That's one of the reasons it is better to use constructs in the programming language, where possible, rather than documentation and comments. For preconditions, postconditions and invariants, you need a language that has support for contracts. For other languages, usually the best you can do is careful choice of names and types, along with assert statements.

Still, Doxygen-like comments in code are usually better synchronised with the code than external documentation!

For the last 20 years or so, virtually all our manuals have been created by our own "literate programming" system called DocGen. DocGen is optimised for Forth, but it would not be a big job to write a version for C.

DocGen diverges from Doxygen and friends in a several ways. In particular it does not need template blocks. If your C code is so bad that another programmer cannot read the declaration, you need far more help than DocGen or Doxgen can give you. The main entry for a function follows the declaration

float someFunc( int how, double x, double y ) // *G The purpose of *\c{someFunc} is ... // ** ... { ... }

The lines starting // *x are formal comments to be processed by DocGen. The *X parts are formatting commands, and the *\{} parts are text macros.

The ideas behind DocGen are that the code and the documentation are never separated, and that the DocGen portion is not much larger than the descriptive comments you should have in your code anyway. Keeping the code in sync with the documentation is a matter of company culture and management.

Whenever we receive third party code to include in our products, we *always* DocGen it before release and we *always* find some bugs. Overall, I estimate that writing the documentation alongside the code costs about 10% extra, paid for by the reduction in bug level.

Stephen