Should I document my private methods? [closed]

Answer 1

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 2

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 3

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 4

(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 5

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 6

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.