example of what I meant on what to doc

[Bob Carpenter]

Andrew mentioned that I'm against certain kinds of doc.
I'm doing some code review and thought I'd provide everyone
some examples.

One of those types is repeating what's in the code and documenting
the language, both of which Google's style guide for C++ warns against.

This example I just found in the code does both:

* ... The autodiff-based implementation for
* reverse-mode are defined in namespace <code>stan::math</code>
* and may be invoked via argument-dependent lookup by including
* their headers.

The namespace declarations cover the first, and ADL is just part
of the language.

What I said is that you should doc things that go against standard
language idioms and best practices, usually hacks to deal with
some external interface or efficiency issue.

Here's an example of something that should be documented by better
variable naming (N_state_size) or just not at all (given that y0 is documented as
the state already, and size() is just size of containers)

// number of states
const size_t N = y0.size();

I'm also not keen on these, but I can live with them:

} // math
} // stan

And just so you don't think I'm saying don't use code comments at all,
this is the kind of thing that's useful:

// initialize forward sensitivity system of CVODES as needed

It's documenting the purpose of a block of code. It'd be even better
to break the block into a function named something like
initialize_forward_sensitivity(...). Then it's self-documnenting and
the code's more modular. In almost all cases,
a block of code longer than a screenful should be broken up into functions (and
lest you think I'm well behaved myself, see lang/generator.hpp for a big
dose of "do what I say, not what I do").

I'm not trying to pick on a particular file or author, just using this
to explain what I meant (and by the way, the file I got these from has beautiful
API doc and is mostly broken up into utility function calls with
descriptive names).

Just to repeat, I'm a very strong proponent of writing doxygen-style
doc for each function. That's what defines the interfaces, lays out
what should be tested, and lets external users use your function without
understanding all its details. That is, encapsulation of implementation,
from which almost all good flows in computer system design.

I wrote a blog post on this a while ago at:

https://lingpipe-blog.com/2009/10/15/the-futility-of-commenting-code/

People always say nobody does this, hence the examples above and

https://lingpipe-blog.com/2009/10/19/examples-of-futility-of-commenting-cod/

- Bob