Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

Post History

60%
+1 −0
Q&A 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 La...

0 answers  ·  posted 7y ago by EJoshuaS - Reinstate Monica‭  ·  last activity 5y ago by System‭

#3: Attribution notice added by user avatar System‭ · 2019-12-08T08:02:41Z (almost 5 years ago)
Source: https://writers.stackexchange.com/q/33508
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/
#2: Initial revision by user avatar EJoshuaS - Reinstate Monica‭ · 2019-12-08T08:02:41Z (almost 5 years ago)
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](https://ericlippert.com/2014/03/05/how-to-debug-small-programs/). 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: Imported from external source by user avatar System‭ · 2018-01-30T17:33:46Z (almost 7 years ago)
Original score: 5