17

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.

Benjamin R
  • 555
  • 6
  • 25
Mihir
  • 2,480
  • 7
  • 38
  • 57
  • 2
    JavaDoc isn't meant for end-users... it's for developers using or working with your code. If you want to address end-users using your software you should search for tutorials of how to write good user-documentation. – Daniel Bleisteiner Mar 23 '11 at 06:40
  • 1
    Sorry , Daniel i mean to say other developers from my team who read and use my java doc . – Mihir Mar 23 '11 at 06:47

3 Answers3

19

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.

didxga
  • 5,935
  • 4
  • 43
  • 58
developer
  • 9,116
  • 29
  • 91
  • 150
2

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.

yvolk
  • 2,391
  • 3
  • 21
  • 26
0

You can use @link parameter for 'VoucherStore'

Example:

@return {@link VoucherStore} type Concrete Object based on storeType parameter

instead of

 @return returns VoucherStore type Concrete Object based on storeType parameter.
Hardik Mishra
  • 14,779
  • 9
  • 61
  • 96
  • 2
    These are bad examples. There is no need to make the whole sentence bold. And the inormation about the return type is very very probably redundant, so leave it out. – Roland Illig Sep 06 '11 at 07:24