[Doxygen-users] RE: [Large] Algorithmics comments or comments inside body functio ns

[Putman, H. <Pu...@di...>]

In my experience developing software, the most important thing about comments is that you are forced to keep them up to date. The best way to keep them up to date is to keep them close to the code they describe. If a description of an algorithm is in the function body, then when the algorithm changes you would naturally change the comments.

I can tell you we have lots of code that has comment header for functions where the parameters, or function names are wrong because someone forgot to come back and change it after they did a cut and paste of a similar function.

The best thing about Doxygen is that it derives alot of its documentation right from the code itself, which is the only part of the code that is garanteed to be accurate.

There are different audiences for generated documentation. I think Doxygen is already set up to accommodate that by being able to do things like not extract documentation for static C functions. Comments in the function body would be like this -- targeted at the development team but not end users.

\return Cheers,

Harold