Homepage
Login
New Post
Profile
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?
(1)More posts by @Margaret427
1 Comments
Sorted by latest first Latest Oldest Best
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.).
Terms of Use Privacy policy Contact About Cancellation policy © selfpublishingguru.com2024 All Rights reserved.