Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

How to write good javadoc comments? [closed]

Tags:

java

javadoc

I am a Java developer, and I'm interested in improving the quality of my Javadoc comments in the code and programs I write to make it more comprehensible and easier for other developers to implement.

I've read lots of articles, including those from official sources, and I try to follow the guidelines stated in the book "The Elements of Java Style", but despite this, and after searching extensively online, I can't seem to find a practical way to compare my existing Javadoc(s) to model examples and maintain best practices for Java API documentation.

like image 615
Mihir Avatar asked Mar 23 '11 06:03

Mihir


People also ask

How do you write a good Javadoc comment?

Writing Javadoc CommentsThey must begin with a slash and two stars, and they can include special tags to describe characteristics like method parameters or return values. The HTML files generated by Javadoc will describe each field and method of a class, using the Javadoc comments in the source code itself.

How do you end a Javadoc comment?

Javadoc scans your source files looking for documentation comments, also known as “Javadoc comments”. They begin with /** (two stars) and end with */ (one star).

Should you write Javadoc for private methods?

Nope, you shouldn't write javadoc for private methods. End users don't have access to private fields or methods so there really isn't a point in providing javadoc for them. Private fields and methods are only meant for the developer. If you really need to though, feel free to write comments for non-obvious logic.

Should Javadoc be above or below annotations?

Javadoc comment is a multiline comment /* */ that starts with the * character and placed above the class definition, interface definition, enum definition, method definition or field definition.


2 Answers

Peer review.

Try and find someone outside your team (a customer) and ask them what they think about your JavaDoc.

The customer is always right.

Also i can share you some stuff below

A great read on writing javadoc is at the sun site at http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html

The best thing I've learned from that text is probably that your class level javadoc should start with "Provides". This forces you to think about what that class provides to your program (or the world). It's not uncommon for me to redesign software because writing javadoc made me think "hey, this is not needed here!".

Other practical tips: When a getter is interesting, try to write it in the @returns tag. Not doing so might mean that you type stuff twice, once in the javadoc, and once after the @return tag.

An the best tip: If you don't know what to write, DONT. the Javadoc parser does a great job of automatically generating getter javadoc for example, but it only does it when you didn't add a /** */.

Javadoc should desccribe WHAT your method does, not HOW.

Javadoc is not your todolist. I've tried it, but for larger projects, it simply doesn't work.

like image 125
developer Avatar answered Oct 12 '22 10:10

developer


In addition to the Sun's (now Oracle) documentation at http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html I would recommend the "Item 44: Write doc сomments for all exposed API elements" from the "Effective Java" book by Joshua Bloch, 2nd ed. pp.203-208. This is a 6 page recommendation/tips with several practical examples.

like image 21
yvolk Avatar answered Oct 12 '22 08:10

yvolk