How to write good Javadoc comments?

I am a java developer. I am interested in improving the quality of my Javadoc comments in the code and programs I write, making them easier to understand and easier for other developers to implement

I have read many articles, including those from official sources, and tried to follow the guiding principle "the elements of Java style" described in this book. However, after extensive online search, it seems that I can't find a practical way to compare my existing Javadoc () model examples and maintain the best practices of Java API documents

Solution

Peer review

Try to find people outside your team (customers) and ask them what they think of your Javadoc

The customer is always right

In addition, I can share some things below

A good reader written on Javadoc is http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html Sun station

Perhaps the best thing to learn from this text is that your class level Javadoc should start with "provide" This forces you to consider what the course provides for your program (or world) It's not uncommon for me to redesign software, because writing Javadoc makes me feel "Hey, it's not necessary!

Other practical tips: when getters are fun, try writing with the @ returns tag Not doing so may mean that you enter it twice, once in Javadoc and once after the @ return tag

One of the best tips: if you don't know what to write, don The Javadoc parser does a lot of work, such as automatically generating getter Javadoc, but you can only do this if you don't add / * * /

Javadoc should describe what your method does, not

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