Do you use javadoc for every method you write?

Question

Should I write Doc comments for all my java methods?

Answer 1

@Claudiu

When I write code that others will use - Yes. Every method that someone else can use (any public method) should have javadoc, at least indicating its obvious purpose.

@ Daniel Spivak

I carefully document every public method in every API class. Classes that have public elements but are not intended for external consumption stand out noticeably in the javadoc class. I also document every protected method in every API class, albeit to a lesser extent. This suggests that any developer who extends the API class will already have a fair idea of ​​what is happening.

Finally, I will sometimes document private and batch private methods for my own benefit. Any method or area that, it seems to me, needs some explanation in its use, will receive documentation, regardless of its visibility.

@Paul de Vrieze

For things like trivial getters and setters, share a comment between them and describe the purpose of the property, not the getter / setter

/** * Get the current value of the foo property. * The foo property controls the initial guess used by the bla algorithm in * {@link #bla} * @return The initial guess used by {@link #bla} */ int getFoo() { return foo; } 

And yes, this is more work.

@VonC

When you break a huge complex method (due to a reason for high cyclomatic complexity ):

• one public method calling
• several private methods that are internal public steps

javadoc is also very useful for private methods, although this documentation will not be visible in javadoc API files.
However, this makes it easier for you to remember the exact nature of the various steps of your complex algorithm.

And remember: limit values ​​or boundary conditions should be part of your javadoc.

Plus, javadoc is better than just "// comment" :

• It is recognized by the IDE and is used to display a popup when you move the cursor over one of your javadoc-ed functions. For example, a constant - a private static final variable - must have javadoc, especially when its value is not trivial. Example: regexp (its javadoc must contain the regular expression in its unescaped form, what is the target, and the literal matched by the regular expression)
• It can be analyzed using external tools (e.g. xdoclet )

@Domci

For me, if someone sees it or not, it doesn’t matter - I’m unlikely to know that some obscure pieces of code that I wrote do in a couple of months. [...]
In short, the logic of comments, not the syntax, and do it only once, in the right place.

@ Miguel Ping

In order to comment on something, you must understand this first. When you try to comment on a function, you actually think about what the method / function / class does, and that makes you more specific and clear in your javadoc, which in turn makes you write more clear and concise code, which OK.

Answer 2

If this method is obviously explicit, I can skip the javadoc comment.

Comments similar to

  / ** Does Foo * /
  void doFoo ();

Indeed, this is not so useful. (Too simplified example, but you understand)

Answer 3

I carefully document every public method in every API class. Classes that have public elements but are not intended for external consumption stand out noticeably in the javadoc class. I also document every protected method in every API class, albeit to a lesser extent. This suggests that any developer who extends the API class will already have a fair idea of ​​what is happening.

Finally, I will sometimes document private and batch private methods for my own benefit. Any method or area that, it seems to me, needs some explanation in its use, will receive documentation, regardless of its visibility.

Answer 4

For things like trivial getters and setters, share a comment between them and describe the purpose of the property, not the getter / setter.

 /** * Get foo * @return The value of the foo property */ int getFoo() { return foo; } 

It is not useful . Better do something like:

 /** * Get the current value of the foo property. * The foo property controls the initial guess used by the bla algorithm in * {@link #bla} * @return The initial guess used by {@link #bla} */ int getFoo() { return foo; } 

And yes, this is more work.

Answer 5

All databases referenced by others; one more note:

If you do this:

 /** * This method currently launches the blaardh into the bleeyrg. */ void execute() { ... } 

Think about it:

 void launchBlaardhIntoBleeyrg() { ... } 

This may seem a little obvious, but in many cases the opportunity is easy to miss in your own code.

Lastly, keep in mind that change is not always required; for example, the behavior of a method can be expected over time (note the word "currently" in the JavaDoc).

Answer 6

When I write code for myself - NO . In this case, joc doccing is a waste of my time.

When I write code that others will use - Yes . Every method that someone else can use (any public method) should have a java document, at least indicating its obvious purpose. For a good test, run the javadoc creation utility for your code (I forgot the exact command line now). Browse the web page that he creates. If you are satisfied with using a library with this level of documentation, you will be gold. If not, write more javadocs in your code .

Answer 7

There is another reason you should use javadocs. In order to comment on something, you must understand this first. When you try to comment on a function, you actually think about what the method / function / class does, and that makes you more specific and clear in your javadoc, which in turn makes you write more clear and concise code, which OK.

Answer 8

No, do not comment on every method, variable, class, etc.

Here is a quote from Clean Code: A Guide to Agile Software Skill:

It’s just silly to have a rule that says that every function should have javadoc, or each variable should have a comment. Comments like this are just a mess up the code, popagate a lie and add to the general confusion and disorganization.

A comment must exist if and only if it adds important information to the intended user of the method, variable, class, etc. What constitutes “important” is worth considering and may be a reminder to me when / if I return to this method / class / etc., the Corollary / side effect of the method, motivation to why the thing even exists (in the case when some code overcomes the drawback / error of a certain library or system), important information about the performance or when it is advisable to call, etc.

Which is not a good comment, but indicates that the code itself needs to be rewritten / modified, it is a comment explaining the details of a complex and obscure method or function. Instead, prefer a shorter, sharper code.

Answer 9

For me, if someone sees it or not, it doesn’t matter - I’m unlikely to know that some obscure pieces of code that I wrote do in a couple of months. There are several recommendations:

• APIs, framework classes, and internal reusable static methods should be carefully commented on.

• The logic in each complex code fragment must be explained in two places - the general logic in javadoc and the logic for each significant part of the code in its own comment.

• The properties of the model should be commented on if they are not obvious. For example, it makes no sense to comment on the username and password, but the type should at least have a comment that says what are the possible values ​​for the type.

• I do not document getters, setters, or anything that is done "from the book." If the team has a standard way of creating forms, adapters, controllers, facades ... I do not document them, because it makes no sense if all the adapters are the same and have a set of standard methods. Anyone familiar with the framework will know what they are for - assuming that the philosophy of the framework and the way it works is documented somewhere. In this case, comments mean additional clutter and have no purpose. There are exceptions to this when a class does something non-standard - then a short comment is useful. In addition, even if I create the form in a standard way, I would like to separate the parts of the form with short comments that divide the code into several parts, for example, “billing address starts here”.

In short, the logic of comments, not the syntax, and do it only once, in the right place.

Answer 10

You should not rely on a Java document because it puts a strain on developers who make changes to support a Java document, as well as code.

Class names and function names should be clear enough to explain what is going on.

If you explain that a class or method makes its name too long to solve, the class or method is not focused enough and should be reorganized into smaller units.

Answer 11

just put: YES

The time when you need to think about whether to write a document is better to embed a document in the document.

Writing a single-line image is better than spending time not even documenting the method at the end.

Answer 12

I believe that at least there should be comments regarding the accepted and returned parameters in terms of what they are.
You can skip implementation details if the function names describe it completely, for example, sendEmail (..) ;

Answer 13

You should probably document all of your methods. The most important are publicly available API methods (especially published API methods). Private methods are sometimes not documented, although I think they should be just for clarity - the same goes for protected methods. Your comments should be informative, and not just repeat what the code does.

If the method is particularly complex, it is recommended that you document it. Some people believe that code should be clearly written so that it does not require comments. However, this is not always possible, so comments should be used in these cases.

You can automate the creation of Javadoc comments for getters / seters from Eclipse using code templates to save the amount of documentation you have to write. another tip is to use @ {$ inheritDoc} to prevent duplicate code comments between interfaces and implementation classes.

Answer 14

in the previous company, we used the jalopy code formatter with eclipse. This will add javadoc to all methods, including private.

This made life difficult for documentary setters and getters. But what the hell. You have to do it - you do it. This made me learn some macro functions with XEmacs :-) You can automate it even further by writing a Java parser and commentator, as the creator of ANTLR, a few years ago :-)

Currently, I am documenting all publicly available methods and over 10 lines in total.

Answer 15

I try, at least, to document all publicly accessible properties and the interface method, so that people calling my code know what it is. I also try to comment as much as possible on the line, as well as for the sake of service. Even the "personal" projects that I do at one time only for myself, I try to execute javadoc only because I can put it in for a year and come back to it later.

Answer 16

I do my best to write javadoc comments whenever this is non-trivial. Writing javadoc comments using an IDE like eclipse or netbeans is not a nuisance. In addition, when you write a javadoc comment, you have to think not only about what this method does, but also about what the method is accurate and about your assumptions.

Another reason is that when you understand your code and reorganize it, javadoc lets you forget what it does, because you can always reference it. I do not advocate forgetting what your methods do, but only because I prefer to remember other things that are more important.

Answer 17

You can run javadoc against code that does not have javadoc comments, and it will generate pretty useful javadocs if you give thoughtful names to your methods and parameters.

Answer 18

It is assumed that in all answers so far the comments will be good. As we all know, this is not always the case, sometimes they are even wrong. If you need to read the code to determine its intent, boundaries, and expected error behavior, there is no comment. For example, this is a thread safe method, can any arg be null, it can return null, etc. Comments should be part of any code review.

This may be even more important for private methods, as the code base developer will have to deal with problems that the API user will not use.

Perhaps the IDE should have a function that allows you to use the documentation form so that the developer can check various properties that are important and applicable for the current method.

Answer 19

Javadoc can be really useful for libraries and reusable components. But let it be more practical. It is more important that I explain the code myself than javadoc. If you fancy a huge project with Javadocs, would you rely on it? I don’t think so ... Someone added Javadoc, then the implementation changed, a new function was added (removed), so Javadoc is deprecated. As I said, I like to have javadocs for libraries, but for active projects, I would prefer

• small functions / classes with names that describe what they do
• clear unit test cases that give an explanation that function / classes do