: Re: 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

@Reiling826

Vote Up Vote Down

I think it really boils down to the fact that there are two different audiences/purposes for the documentation.

Documenting private methods probably isn't super important when it comes to generating documentation for your application overall. In that setting, you're probably more concerned about the purpose of the components more so than the implementation.

However, when reading/modifying/extending the code, it the implementation is often more relevant. Especially for larger files or less frequently used code, documentation on private methods can be really helpful. For developers using an IDE the documentation can be provided as developers are working on the code, avoiding the need to jump down to the method declaration. Even if not using an IDE, some amount of documentation can at least prevent the need for reading the implementation of a private method to figure out what it's doing, and possibly also give clues as to the intent. This should hopefully also be conveyed by the name of the function, but sometimes a rephrasing or clarification in documentation can be helpful and time-saving.

Beyond that, I think it's just a judgement call. Most developers I know tend to go pretty light on the documentation though probably mostly out of laziness or not feeling it's necessary. My perspective is that it's not vital but wherever you have something that's being especially clever (e.g. heavily optimized code) or just doesn't have a perfect name, it's a good idea to add a sentence or two about why it's there, even if its just a plain non-documentation comment. Where you fall on that will probably depend on the complexity of the code you're writing, the size of the codebase, the expected lifetime fo the code, and the number of people that might edit it. All of those factors are good reasons to include more documentation, especially for implementation details (i.e. private methods, white box tests, etc.).

(0)

Login to post a comment!