Should I document my private methods? [closed]

Answer 1

Personally, I feel that it is. Documentation is often the most useful to future developers maintaining your software - especially member documentation.

Even public API documentation is only of limited use to any audience other than a developer. Document for those following - they will thank you.

Answer 2

I wouldn't. If your private methods need documentation it may be worth be spending time making your code cleaner in this area.

Edit: even with a summary I would not document. Private methods can change, sprout anew, disappear. One of the basic tenets of OO is one of encapsulation. You don't need to know what a private method is doing. And as for developers, who is going to keep up to date all this documentation? First time you but in future?

Edit 2: From comments

I strongly disagree. The only time a private method shouldn't be documented (in some way) is when its purpose is completely obvious from its name and its source code. If there is anything "clever" about your code at all, it deserves a comment explaining why you're doing it that way.

I strongly agree but.. code shouldn't be 'clever', code should be functional and readable. Most of the time you should aim for your code to be as transparent as possible to the reader, if you need to comment it, then you should look at making your code clearer before you hit javadoc (or whatever you use).

Edit 3:

What would you much rather see.?

/**
*   This method doesn't do what you expect it to.
*   Below you will find a whole ream of impenetrable
*   code. Where there are bits that look that they do x, they don't
*   they do y. 
**/
private void someComplexInternalMethod()
{
     ...
     badly named variables
     comments to describe intent
     perhaps some out of date orphaned comments
     as code has been removed but comment remains

     ....
     ....
     looong methods 
}

private void WellNamedMethod()
{
     ...
     well named variables
     shorter method, highly cohesive
     self documenting
}

Answer 3

Well, that code should be maintainable too, don't you think? Of course they should be documented! You're going to have to look over that code in a couple of months and you're going to want to have something to refer to when making a change.

Answer 4

It definitely is. In anything but trivial software, you can make it faster to comprehend the code with the proper use of comments, even for the original author a few months later.

Answer 5

Absolutely. Always write code with the assumption that you will be required to modify it two years later. The method summary is the most important of all. I can't tell you how many times i've caught bugs because I was writing the doc (summary, arguments, return) and realized I'd missed something.

Answer 6

You should refactor your code for clarity so that implementation documentation isn't necessary.

Don't use your ability to comment your code to allow you to be lazy in writing obvious code in the first place.

Documentation that says the same thing your code says but in a different language is redundant. And like redundant code, this redundancy has to be maintained too, but often isn't.