CODEWITHSUNDEEP
javajavadocconventions
Rasto
Rasto

Reputation: 17844

What should have javadoc in Java?

What should be documented by javadoc comments (classes, methods, constructors and fields? Or only classes methods and constructors?)? Is there any convention about that ?

Please provide links to relevant resources in your answer whenever possible. Thank you

EDIT: The question is not about how is it usualy done or what is logical to comment with javadoc. The question is what can be found about this matter in any official Sun/Oracle documents (guidelines about writing javadoc, conventions, specifications and so on). Also please do not answer about how should the javadoc comments look like, the question is specifically about what should be commented, not how.

Upvotes: 3

Views: 5039

Answers (3)

YoK
YoK

Reputation: 14505

Simple and general rules for javadoc as mentioned by Thilo and also from here should be as follows :

Javadoc Guidelines

General Rules

  • All public and protected methods must have full documentation
  • Trivial getters and setters are exempted from this rule. Doing
    anything but returning or changing a
    variable in a getter or setter should be documented.
  • Private methods with non-obvious implementations should have enough
    documentation to allow other
    developers to debug them

Official guidelines are found here : How to Write Doc Comments for the Javadoc Tool

Upvotes: 4

Thilo
Thilo

Reputation: 262834

Javadoc is to document the public API of your code.

In a nutshell, you need to document all your public and protected classes, methods, constructors, and fields (because they are accessible to your users).

You need to describe what a method does, not how it does it. Of course, if implementation details result in interesting side-effects, for example performance characteristics, and also usage limitations, those should be mentioned.

Oracle has official guidelines on "How to Write Doc Comments for the Javadoc Tool".

Upvotes: 7

Brad Mace
Brad Mace

Reputation: 27916

Imagine showing the code to someone else who is familiar with the programming language, but not your project. Whichever parts you feel the need to explain as you're watching him review it should be documented.

similar question on programmers.SE: Should you document everything or just most?

Upvotes: 0

Related Questions