Are there valid reasons to write Java Annotation (or .NET XML Documentation) for private methods?

At this point, many languages have some "standard" format for writing documentation for individual methods. This includes, for example, Java Annotation and Microsoft's XML Documentation for .NET Languages. These formats are generally highly structured in order to be suitable for use by tools like Sandcastle and Javadoc to automatically generate documentation.

As a general rule, public methods and classes should be documented in this way (because that's what library/API users will actually be interacting with). However, what about private methods? It seems like it's a good idea to have at least some kind of documentation in order to ease maintenance. "Write a specification for each of your methods" also appears in Eric Lippert's notable article on debugging techniques. As he describes it,

While you’re refactoring your methods into smaller methods, take a minute to write a technical specification for each method. Even if it is just a sentence or two, having a specification helps. The technical specification describes what the method does, what legal inputs are, what expected outputs are, what error cases are, and so on. Often by writing a specification you’ll realize that you forgot to handle a particular case in a method, and that’s the bug.

This actually sounds a lot like .NET's documentation, which "by default" provides a template for summarizing the method, explaining what each parameter is, and explaining the return value - in Visual Studio, you just have to type /// and the IDE will insert this for you. That being said, this seems like a really natural way to follow Eric Lippert's advice.

On the other hand, Java Annotation and similar formats can add a lot of "bulk" to your code, and there are probably more concise ways to document them.

What are some arguments for or against using these formats for private methods?

posted about 6 years ago

CC BY-SA 3.0

EJoshuaS - Reinstate Monica‭

10 reputation 2 0 1 0