Should I document my private methods?

Question

Private methods documentation can only be seen by who has access to the source code. Is it worth the effort spent on it?

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

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 4

Yes, definitely. In six months you might need to come back and do some maintenance. A couple of well-placed comments could save you a lot of time and effort. You maybe don't need to document it to the extent you would a public API but a few comments never hurt.

Answer 5

When you visit your private methods 6 months from now, will they make as much sense to you as they do now? Will you need to spends hours trying to trace the relationships between components?

In my experience, good documentation is never a waste of time.

Answer 6

Yes, it is necessary to document your private methods. It becomes increasingly necessary as more developers are using your code, and are modifying your code. Private methods guarente a specific functionality just like public methods. The difference is how the code is used. Documentation of private methods accelerates refactoring down the line.

Answer 7

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 8

Yes, yes, yes. Document any code that you write.

Eventually someone will be maintaining the code that you write. Documentation is a way for you to help them get into the mindset you had when writing that particular piece of code. Private functions are especially important to document because they tend to have the least amount of usages in your code from which a developer can infer their invariants.

Answer 9

Documenting public methods is useful for both maintainers and people who use your package.

Documenting private methods is useful for maintainers or your package (including you).

In short, it's neccessary in a slightly different way. For example, documenting private methods doesn't need to be formal.

Answer 10

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.

Answer 11

If your method names don't make their purpose immediately obvious then they aren't well-named. Relying on documentation over well-named classes & methods will invariably come back to bite you. All it takes is a few instances of people forgetting to update the documentation and you end up with a horrible mess. example:

BAD

private void Update(string sValue, DateTime dValue)
{...}

BETTER

private void UpdateEmployeeInformation(string jobTitle, DateTime hireDate)
{...}

What about the second version needs documenting? The name identifies what its purpose is and the param names make it obvious what is expected to be passed.

If your methods are so long and complex that they require a novel to explain you need to break them up into logical bits of functionality that can be well-named and highly focused. That, IMHO, is much easier to understand than some poorly written inline documentation that may or may not be up to date - I'm STILL going to read through all of the code to make sure it matches what the documentation says it should do and in most cases I'm going to assume that the documentation hasn't been maintained and ignore it.

You should also have unit tests that flex the code and make the functionality even MORE obvious. With well-named classes, methods, and unit tests what purpose does additional documentation serve?

Answer 12

Any method that does something complex enough to be both interesting and non-obvious is worth the time to clarify it by some documentation.

Answer 13

Yes. As this joke I heard:

Programming is like sex. One mistake and you have to support it to the rest of your life.

Answer 14

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 15

For public interfaces (e.g. public methods and classes), document the purpose of each method -- you want to describe your public interface (i.e. your code contract) as clearly as possible.

For private members (where you will actually do the work), you may want to document the purpose of methods. But it is much more useful to document your algorithms -- why and how, not just a description of the code.

Any future developer who has access to your private members will have access to your code as well. If I can read your code, I can figure out what it's doing. But unless I can read your thoughts, there is no way I can figure out why your code does what it's doing -- except if you write some documentation explaining it to me.

Answer 16

Private methods are generally a way to isolate a code which would have been too massive to maintain in one public method.
As part of a refactoring process, you divide this code into several private method.

What I have always seen after this step is this question, even when the developer is the very same one having written those private methods:

Why did this method has to be called already?

So, it is not so much about what this method does (its name should be explicit enough), but about why it exists (for what purpose, in what context).

• What it does should be explained by the name, and some internal comments inside the code.
• But having the "reason why the method is there" directly in the API documentation allows the developer to see that documentation directly in the context of the calling method, by hovering its mouse above the private call.
  And that, even a mere week after written all those private functions, can be very (very) useful.

Answer 17

Only if you have got nothing better to do. Therefore - probably - no.

Answer 18

I shall take the unpopular stance, and say no.

Many of my private methods would otherwise be complex statements in a method, statements that would require a comment. Half the reason of making them a private method is to clarify the code and reduce the need to document what it does.

Documentation needs to be maintained & updated whenever the code changes. You are now asking a maintenance developer to do the same work twice. Once to fix the bug, and once to explain the fix.

In my experience the second action often doesn't happen. I inherited a 5+ year old code base when I started here. In one particular app, about half of everything had been commented, often - VERY often - the comments bore little or no resemblance to the actual code. Either the dude was on acid when he wrote them, or he wrote the comments with the first cut of code, then code changed and the comments didn't.

Now I pretty much pull out his comments without reading them. Each app, or logical module within a large app has a 1 or 2 page document outlining it's general purpose, general structure and anything that's out of the ordinary.

We expect developers to be able to write readable code, and new hires to be able read readable code.

Now, let the down-voting begin!

Answer 19

(against the consensus) I emphasize self-documenting code (public though private). This can be tremendously effective, you will need to formally document much less. Some people really dislike this (sometimes for good reasons). Since you're mentioning private implementation, your constraints to rename and modify over time are far fewer. An interface with a handful of special cases is a recipe for failure (yet they are still produced).

Documentation: If it is going to consume the majority of the header, it had better be meaningful.

I have a habit of zapping bad/meaningless documentation because, like the interface, none is better than bad. hehe

Answer 20

Personally I believe a more in self documenting code that in code documentation. The heavy use of intent-revealing-names, side-effect-free functions, etc.

But sometimes it is not possible to let the code be self documentary, and in that case, I will always document the functions, or the inner workings.

Answer 21

These days I often write the class/method level documentation before starting on the code. This is particularly helpful in keeping classes well defined and methods single-purpose, because you have a reminder right there in front of you that will tell you when your class/method has evolved outside beyond your original intention.

I don't like writing documentation any more than anybody else who can write code, however I don't find that it eats coding/debugging time, as the act of explaining back to yourself what you are about to do is all about improving the output from your thinking time.

Method comments also provide a useful double check, because if the code doesn't do what the comment says it does, then that's something worth looking into when debugging.

From a code reader's perspective, since useful code will be read many (hundreds/thousands) more times than it is written, comments that document the code contract save the reader from having to work out what the code does at the next level of detail. When you're skim-reading many thousands of lines of code this saves expensive mental context switches from skim reading to analysis and back.

The people who spend a large part of their working day reading large amounts of code are the team-leaders and architects who are responsible for keeping the systems working, and negotiating with management on behalf of their development team(s). Even well written code is hard to read quickly and in quantity, because the bulk of it will be at a different level of abstraction from the level that the reader is interested in.

If the people who represent the development teams can't read the code quickly, it's hard to have evidence-based discussions with managers, and decisions are made without being influenced by the technical realities.

Repeated many times over, this leads to difficult issues for the development team, which could have been avoided by applying a bit of engineering discipline at the detailed level.

Not all systems are large, complex and short on gurus who just know the answer, but some systems are like that, and they can get that way suddenly. The next generation of gurus-in-training will thank you for documenting your code.

Answer 22

What about private fields? For a Serializable class private fields must be documented. From "Effective Java" by Johsua Bloch:

Private fields define a public API, which is the serialized form of the class, and this public API must be documented. The presence of the @serial tag tells the Javadoc utility to place this documentation on a special page that documents serialized forms