[C++] Where are doxygen comments appropriate/necessary?

Question

I don't have much experience with documentation tools like doxygen, so I'm not sure exactly how in-code documentation should look.

Should I write doxygen-style comments for each member variable in a class? Or is this overkill if the variable names are fairly self-explanatory?

Should I include the comments from a header in the corresponding implementation file? I'm guessing no, since anybody changing the comments in one file would have to make the same change in the other; but it would certainly be convenient for developers working on the implementation not to have to consult the header file to know the purpose of a given method.

Answer 1

Should I write doxygen-style comments for each member variable in a class? Or is this overkill if the variable names are fairly self-explanatory?

That's at least partially a style issue. Different people do it different ways.

I generally think everything that's either public or protected should be documented, as that's the API your class is providing (protected is part of the API you give to anyone who's going to extend your class).

For some methods it can be overkill when the method is simple enough, like simple getters and setters. I still document those anyway, but it's probably not a huge deal if you don't. However, if you don't include documentation for everything make sure doxygen is configured to output documentation for everything, not just the fields/methods you document. Otherwise the undocumented methods and fields won't show up in the output.

Should I include the comments from a header in the corresponding implementation file? I'm guessing no, since anybody changing the comments in one file would have to make the same change in the other; but it would certainly be convenient for developers working on the implementation not to have to consult the header file to know the purpose of a given method.

Only write the documentation once. The purpose of the doxygen-style comments is so that the person using the class doesn't have to look at the code (header file or otherwise). They'd look at the documentation generated by doxygen, which will be nicely formatted and linked. As long as your documentation comments are useful then the doxygen output will probably be easier to use than going through and looking at the code.

Answer 2

One of the ideas of doxygen is that you can convert a simple descriptive comment about a member into a documentation comment by just adding a <

e.g.

int anUndocumentedVariable;     // This is used for things and stuff
int aDocumentedVariable;        //< This is used for things and stuff

So if you can be bothered explaining the use of the variable, making it doxygen friendly is a trivial matter - so the question is really "why not?".

As to when documentation is needed: If class, method and variable names are well written, then the code should be relatively self describing. Where commenting/documentation is of benefit is in the following cases:

• To summarise. Sometimes a brief summary of something is a lot quicker to read and understand than the code, even if the code is amazingly readable.

• To explain context or the bigger picture. People using or maintaining your code can work out what "deleteWhenFinished" means. What's not so obvious is when/why would you want to deleteWhenFinished? Do you need to set deleteWhenFinished if you have deleted the object yourself, or will that cause a crash? etc. Or you might have a paragraph that explains the design of the class, giving the reader a quick overview of what it is for and how it should be used.

• To explain why something was implemented in a particular way. e.g. "We can't do XYZ here because it needs to interact well with the ABC system."

• To explain any useful information that is not immediately obvious, e.g. "This parameter can NOT be null", or "You must call Initialise() before calling this method".

Often people suggest that you only need documentation on public members, to make it easier for other programmers to read your code. But that's rubbish - the first programmer who needs to maintain your code will hate you for it. And that programmer will often be yourself in 3 months time!

Of course, you should never waste time writing useless comments:

bool deleteOnCompletion;  //< Deletes on completion

You shouldn't need to ask "should I document this". If you can use tools like my AtomineerUtils add-in for Visual Studio, 95% of the comment body can be filled in for you automatically, updated automatically if you subsequently change the code, and word wrapped and tidied automatically, so documenting really doesn't have to be a chore.

Just to add a counterpoint to the last answer, I almost never use "external" doxygen-generated documentation - I find it a pain to switch between my code view and a documentation page. I simply press f12 to go to the definition of a method and read the doxygen/docxml documentation comment directly from the code.