Code documentation: Public vs. Non-Public?

Question

I'm one of those developers that has the mindset that the code written should be self-explanatory and read like a book.

HOWEVER, when developing library code for other people to use I try to put as much documentation in the header files as possible; which brings up the question: Is documenting methods that are non-Public even worth the time? They won't be using them directly, in fact, they can't. At the same time if I distribute the raw code (albeit, reluctantly) those non-Public methods will be visible and may need explaining.

Just looking for some standards and practices that you all see or use in your travels.

Answer 1

I would never consider omitting documentation for internals just because an "end user" won't be using them; code maintenance is more than enough reason to include documentation comments for all components, in fact especially for internals which tend to be the most complex (and oft-changing) part.

That said, there may be a valid case to be made for keeping them restricted to the non-header source code (rather than publicly documented), in order to maintain the abstraction.

This is all rather subjective, mind you.

Answer 2

Ok, i add my way of commenting/documenting too to the picture for variety. Rationale is that i avoid describing functions or member functions that are only declared there in header. On one hand i fear to add too much noise to header. On other hand documentation together with definition is easier for maintainer to match. Doxygen does not care either way and can filter privates out if needed.

In class header:

• included headers (why)
• class definitions always (purpose and responsibilities)
• the pure virtual functions always (full contract)
• the inline functions unless self-explanatory getters
• other declared types unless self-explanatory
• static data members (why)
• other data members unless self-explanatory
• the macros if any (contract and why)

In class implementation code:

• local declarations same way as in header
• function definitions always (full contract)
• member function definitions always (full contract or reference to root of virtual override)
• static variables defined if any (purpose why)

In template header:

• the above merged and
• suitable/unsuitable types for template arguments and
• how well suitability is statically detected

Answer 3

The private: at the beginning of the private section is all the documentation users should need.

Answer 4

Documentation is any day worth it, it helps to explain use cases and stories in a brief manner. How much ever the code is self explanatory it cannot explain the business as easily as few lines of story telling. The code would definitely require the user to follow through logic in addition to understand what is going on. :-) My 2 cents...

Answer 5

Definitely!

That code should be self-documenting is a slogan to live by. Yet, I would go so far as to say that private code needs as much documentation, if not more, than public code, because it's usually here that the most assumptions usually take place, just because the coder assumes that it will remain in the dark. So, a couple of months later, when a bug comes your way, you will spend time trying to remember what was the idea behind the code (perhaps you yourself) wrote.

Documentation shouldn't be there as a nice gift to others. Documentation, in all its faces (well-picked variable names, self-documenting class names, well-organized code, properly segmented methods, etc) is a gift to everyone who may come in contact with your code, yourself included.