Ftn I/Os documentation best practices

I add a boilerplate to each function definition that declares constraints on inputs, expectations of outputs, performance issues, etc. I use this to add invariants to the code to detect/enforce these conditions.

But, there is nothing that ensures that I've done this -- other than discipline.

I'm looking at ways to create an IDL that will allow for more specific criteria to be included in the declaration that could also drive the IDL compiler to add suitable invariants as applicable.

[This makes RPC much more effective but can also benefit traditional ftn invocations]

Any pointers to similar schemes? I've been looking through CORBA et al. for hints but they seem to focus on bigger machines (where there is more tolerance over data types and more overhead expected).

Reply to
Don Y
Loading thread data ...

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).

Reply to
David Brown

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.

Reply to
Grant Edwards

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!

Reply to
David Brown

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 Pelc, stephen@vfxforth.com 
MicroProcessor Engineering, Ltd. - More Real, Less Time 
 Click to see the full signature
Reply to
Stephen Pelc

ElectronDepot website is not affiliated with any of the manufacturers or service providers discussed here. All logos and trade names are the property of their respective owners.