Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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.

share|improve this question

migrated from stackoverflow.com Jun 2 '11 at 18:45

This question came from our site for professional and enthusiast programmers.

5 Answers 5

up vote 11 down vote accepted

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.

share|improve this answer
1  
I agree, if you want the code to be maintained, you need to make it as obvious as possible what each part of it is trying to achieve, whether it is private or not. I'm sure you can choose whether or not to generate the private documentation in Doxygen. –  Gary Buyn Jun 1 '11 at 0:13

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
share|improve this answer

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

share|improve this answer

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

share|improve this answer
    
OK, but you don't address the distinction between documentation for the public API and documentation for internal workings. –  Lightness Races in Orbit May 31 '11 at 23:49

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.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.