What is the purpose of (what look like) annotations placed in comments? For example, I'm seeing the following comment above a method in an interface:
/**
* Create saved search
* REST: POST /lifecycles/savedsearches
* #param controlParameters control parameters
* #param search savedSearch object
* #throws ProcessingException if any processing exceptions
* #return Updated Object
*/
I understand the meaning of the comment, just wondering why this syntax was used.
These annotations are important for the javadoc tool. When it generates a documentation for a class/interface/enum/constructor/method if parses the content between /** and */.
For a single piece of javadoc content, the tool generates a HTML-based documentation, which consists of several paragraphs. When it detects an annotation (e.g. #param) it adds the corresponding #param information to the paragraph about the Parameters of a method.
Checkout the String#concat(String str) method, for example.
Also, take a look on the Oracle's Javadoc home page
This is used when generating Javadoc. That way you can add an explanatory text for each parameter passed to the function and you can explain what's returned and what exceptions can be thrown and the Javadoc generator then adds your comments to the methods documentation in its corresponding places.
Then you can use that to generate html pages documenting your code based on these comments.
It's used then for javadoc generation. See http://www.oracle.com/technetwork/articles/java/index-jsp-135444.html
This syntax is used if you generate Javadoc.
http://www.oracle.com/technetwork/articles/java/index-137868.html
i'm working with Eclipse in Java and with long long classes i need a feature like this: in the top comment of a method (for example) there is a list of operations executed by the method.
For each operation listed, i'd like to "hyperlink" a portion of the comment to a specific line of the related code.
Then using Ctrl+Click to that line i can jump directly to the specified line code.
Is it possible an operation like this?
Thanks
In the comment below your question you say:
how can i link methods?
Take a look at the following example: you can press ctrl + click on bar() within the JavaDoc of foo() and eclipse jumps to the method bar().
public class Example {
/**
* JavaDoc of foo(). This method executes {#link Example#bar()}
*/
public void foo() {
bar();
}
/**
* Javadoc of bar().
*/
public void bar() { }
}
Eclipse even offers autocomplete for #link, the classname and the method (after you manually entered the #).
Is that what you are looking for?
You can use the JavaDoc #see tag:
/**
* #see MyClass#myMethod()
*/
This generates a hyperlink in your JavaDoc.
SRC: method-linking-anchoring-in-java
The Eclipse IDE allows you to go from a method call to the method's definition ('F3' I think).
Apart from that, I don't think there's a way to set up "special" navigation. Mind you, if you need something like that, it is a strong indication that your methods are WAY too large. Refactor them.
Thinking outside of the box, if you were to feed your code through a code-to-html pretty printer, you could embed HTML hyperlinks and anchors in comments (javadoc or normal). With a bit of luck, they would be clickable when you viewed the HTML-ized source code in a web browser.
Of course, Eclipse can follow javadoc "links". Obviously the standard tags can't link to deep inside a method, but I guess you could write an Eclipse plugin that supported non-standard javadoc tags for linking to embedded anchors, and the navigation thereof.
is there a reason i should prefer to write inline-comments in java like this:
/** Init operation */
mindControlLaser.engage();
as opposed to use just one *:
/* i'm a happy comment */
Eclipse colours the syntax differently, but is there really anything in the "toolchain" (javadoc, eclipse, etc.) giving me an advantage when using /** */ ?
No reason for inline comments.
/** signals to javadoc utility to extract documentation about your API automatically. It does not have any effect when is used inside methods.
Regular comments
/* Regular comment */
With regular comments you explain maybe a part of an algorithm that is tricky.
Or anything that you don't want to be a part of the JavaDOC. Inline comments are regular comments too, and can be used for example when the description is shorter.
Java Documentation
/** JAVA DOC COMMENT */
With javadoc you explain classes, methods, or fields(variables).
Then, most IDEs like Eclipse can use this information to help you while you code.
For example, if you have a classA and a classB, and in classB you use stuff from classA, then if you hover on methods or variables you can see the JavaDOC information. It's very handy.
Also, with build tools like ant you can automatically build HTML files out of the JavaDOC, and if you publish them you can allow others to reuse your work.
Look for example the documentation of Java itself here.
The syntax for a comment is /* */.
Javadoc has as a default that you use /** */. This is a comment because the second * is inside the comment, so would not be seen differently by your compiler.
So without a second * you are just adding a comment, and with the second one you write javadoc: eclipse will recognize it and give you hints etc when hovering on the functioncall somewhere else.
/** .... */ will generate Javadoc, /* ... */ won't.
Of course, it will generate Javadoc only when in the correct places. Javadoc also has a pretty well defined format, see here.
The /** denotes "documentation" comments; Javadocs etc. look for these when creating documentation for your code.
So they should really only be used above methods and classes, e.g.:
/**
* Class to represent tigers.
*/
class Tiger {
/**
* Go extinct.
*/
void goExtinct() {
}
}
The /* variant just denotes a standard comment block.
Yep, it's the javadoc notation to use /** Primary sentence. Other descriptions... */. First sentece up to the . will be used in summaries of javadoc and the rest in the detailed view.
Javadoc treats /** differently; classes and methods which have /** comments above them will get put into javadoc output.
If you use the reference formatting (e.g. {#link ClassA}) and rename the class ClassA with Eclipse, it will automatically update the comment if it is a javadoc comment.
I am working on someone else's code and making significant modifications. (I am converting it to use a different database than the one he originally used.) How do I indicate in the Javadoc comments that I am not the original author of the code, but that I did make contributions to it. Is there a clean or standard way of doing this already? My Googling is not helping me figure this out.
Example:
/**
* This class does some really awesome stuff.
*
* #author Steph the Great - Modified to use PostgreSQL instead of Derby;
* added comments to the code
*/
I also don't know the original author's name, so all I can put down is myself . . .
Those comments do not belong in the javadoc :-) The javadoc should explain the contract -- it is what is extracted and displayed in the auto-generated "documentation". The rest are just normal comments or, perhaps better yet in this case, SCM log entries and have no place in the javadoc!
I would likely just leave the original author, but if you want credit...
...see the #author javadoc reference and note that it can be included multiple times. This section explicitly relates to multiple authors and ordering, etc.
/**
* This class does some really awesome stuff.
* It uses PostreSQL.
*
* #author Steph the Great
* #author Freddy Four Fingers
*/
// DEC2012 - Fred - Modified to use PostgreSQL instead of Derby (but really, use SCM!)
class Awesome { ... }
Happy coding.
Notes on question somewhat unrelated to example in post... if the author isn't known, then several things can be done. First and foremost add a link or reference to where the original source was obtained -- an optional "I didn't write this originally" for clarity can be noted as well.
Then, depending upon your preference:
Don't specify an #author field -- not even yourself. It's not required.
Add yourself as the sole author; the original source is mentioned above in the javadoc
Add a dummy author and yourself as the second author, e.g. #author Unknown #author unascribed (see comments and #author).
Do whatever you want within terms of the license, if any.
You can have more than one #author tag. So, if you've made extensive changes to a class, just add a new #author tag with your own name in it. There's no need to list the changes you've done---the revision history should show that well enough.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 4 years ago.
Improve this question
Should I be writing Doc Comments for all of my java methods?
#Claudiu
When I write code that others will use - Yes. Every method that somebody else can use (any public method) should have a javadoc at least stating its obvious purpose.
#Daniel Spiewak
I thoroughly document every public method in every API class. Classes which have public members but which are not intended for external consumption are prominently marked in the class javadoc. I also document every protected method in every API class, though to a lesser extent. This goes on the idea that any developer who is extending an API class will already have a fair concept of what's going on.
Finally, I will occasionally document private and package private methods for my own benefit. Any method or field that I think needs some explanation in its usage will receive documentation, regardless of its visibility.
#Paul de Vrieze
For things, like trivial getters and setters, share the comment between then and describe the purpose of the property, not of 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 (because of high cyclomatic complexity reason) into:
one public method calling
several private methods which represent internal steps of the public one
, it is very useful to javadoc the private methods as well, even though that documentation will not be visible in the javadoc API files.
Still, it allows you to remember more easily the precise nature of the different steps of your complex algorithm.
And remember: limit values or boundary conditions should be part of your javadoc as well.
Plus, javadoc is way better than simple "//comment":
It is recognized by IDE and used to display a pop-up when you move your cursor on top of one of your - javadoc-ed - function. For instance, a constant - that is private static final variable -, should have a javadoc, especially when its value is not trivial. Case in point: regexp (its javadoc should includes the regexp in its non-escaped form, what is purpose is and a literal example matched by the regexp)
It can be parsed by external tools (like xdoclet)
#Domci
For me, if somebody will see it or not doesn't matter - it's not likely I'll know what some obscure piece of code I wrote does after a couple of months. [...]
In short, comment logic, not syntax, and do it only once, on a proper place.
#Miguel Ping
In order to comment something, you have to understand it first. When you trying to comment a function, you are actually thinking of what the method/function/class does, and this makes you be more specific and clear in your javadoc, which in turn makes you write more clear and concise code, which is good.
If the method is, obviously self evident, I might skip a javadoc comment.
Comments like
/** Does Foo */
void doFoo();
Really aren't that useful. (Overly simplistic example, but you get the idea)
I thoroughly document every public method in every API class. Classes which have public members but which are not intended for external consumption are prominently marked in the class javadoc. I also document every protected method in every API class, though to a lesser extent. This goes on the idea that any developer who is extending an API class will already have a fair concept of what's going on.
Finally, I will occasionally document private and package private methods for my own benefit. Any method or field that I think needs some explanation in its usage will receive documentation, regardless of its visibility.
All bases covered by others already; one additional note:
If you find yourself doing this:
/**
* This method currently launches the blaardh into the bleeyrg.
*/
void execute() { ... }
Consider changing it into this:
void launchBlaardhIntoBleeyrg() { ... }
This may seem a bit obvious, but in many cases the opportunity is easy to miss in your own code.
Finally keep in mind that the change is not always wanted; for instance the behaviour of the method may be expected to evolve over time (note the word "currently" in the JavaDoc).
For things, like trivial getters and setters, share the comment between then and describe the purpose of the property, not of the getter/setter.
/**
* Get foo
* #return The value of the foo property
*/
int getFoo() {
return foo;
}
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.
No, do not comment every method, variable, class, etc..
Here's a quote from "Clean Code: A Handbook of Agile Software Craftsmanship":
It is just plain silly to have a rule that says that every function must have a
javadoc, or every variable must have a comment. Comments like this just clutter
up the code, popagate lies, and lend to general confusion and disorganization.
A comment should exist if, and only if, it adds important information for the intended user of the method, variable, class, etc.. What constitutes "important" is worth consideration and could be a reminder to myself when/if I come back to this method/class/etc., a consequence/side effect of the method, motivation for why the thing even exists (in the case where some code is overcoming a shortcoming/bug of some library or system), important information about the performance or when it is appropriate to call, etc..
What is not a good comment but indicates the code itself should be rewritten/modified is a comment explaining the details of a complex and obscure method or function. Instead, prefer shorter clearer code.
When I write code for myself - NO. In this case, java doccing is a waste of my time.
When I write code that others will use - Yes. Every method that somebody else can use (any public method) should have a java doc at least stating its obvious purpose. For a good test - run the javadoc creation utility on your code (I forget the exact command line now). Browse through the webpage it generates. If you would be satisfied using a library with that level of documentation, you're golden. If not, Write more javadocs in your code.
There is another reason you should use javadocs. In order to comment something, you have to understand it first. When you trying to comment a function, you are actually thinking of what the method/function/class does, and this makes you be more specific and clear in your javadoc, which in turn makes you write more clear and concise code, which is good.
simply put: YES
The time you need to think about whether you should write a doc,
is better invested in writing a doc.
Writing a one-liner is better than spending time for not documenting the method at all in the end.
For me, if somebody will see it or not doesn't matter - it's not likely I'll know what some obscure piece of code I wrote does after a couple of months. There are a few guidelines:
APIs, framework classes, and internal reusable static methods should be commented thoroughly.
Logic in every complicated piece of code should be explained on two places - general logic in javadoc, and logic for each meaningful part of code in it's own comment.
Model properties should be commented if they're not obvious. For example, no point in commenting username and password, but type should at least have a comment which says what are possible values for type.
I don't document getters, setters, or anything done "by the book". If the team has a standard way of creating forms, adapters, controllers, facades... I don't document them, since there's no point if all adapters are the same and have a set of standard methods. Anyone familiar with framework will know what they're for - assuming that the framework philosophy and way of working with it is documented somewhere. In this cases, comments mean additional clutter and have no purpose. There are exceptions to this when class does something non-standard - then short comment is useful. Also, even if I'm creating form in a standard way, I like to divide parts of the form with short comments which divide the code into several parts, for example "billing address starts here".
In short, comment logic, not syntax, and do it only once, on a proper place.
Java doc should not be relied on, as it places a burden on developers making changes to maintain the java doc as well as the code.
Class names and function names should be explicit enough to explain what is going on.
If to explain what a class or method does makes its name too long to deal with, the class or method is not focused enough, and should be refactored into smaller units.
I feel there should at least be comments regarding the parameters accepted and return types in term of what they are.
One can skip the implementation details in case the function names describes it completely, for eg, sendEmail(..);
I make it a point to write javadoc comments whenever it is non-trivial, Writing javadoc comments when using an IDE like eclipse or netbeans isn't that troublesome. Besides, when you write a javadoc comment, you are being forced to think about not just what the method does, but what the method does exactly, and the assumptions you've made.
Another reason is that once you've understood your code and refactored it, the javadoc allows you to forget about what it does since you can always refer to it. I'm not advocating purposely forgetting what your methods do but it's just that I prefer to remember other things which are more important.
You should probably be documenting all of your methods really. Most important are public API methods (especially published API methods). Private methods are sometimes not documented, although I think they should be, just for clarity - same goes with protected methods. Your comments should be informative, and not just reiterate what the code does.
If a method is particularly complex, it is advised that you document it. Some people believe that code should be written clearly so that it doesn't require comments. However, this is not always possible, so comments should be used in these cases.
You can automate the generation of Javadoc comments for getters/setters from Eclipse via the code templates to save on the amount of documentation you have to write. another tip is to use the #{$inheritDoc} to prevent duplication of code comments between interfaces and implementation classes.
Javadoc can be really useful for libraries and reusable components. But let's be more practical. It is more important to have self explaining code than javadoc.
If you imagine a huge legacy project with Javadocs - would you rely on that? I do not think so... Someone has added Javadoc, then the implementation has changed, new feature was added (removed), so the Javadoc got obsolete.
As I mentioned I like to have javadocs for libraries, but for active projects I would prefer
small functions/classes with names which describe what they do
clear unit test cases which give explanation what the
function/classes do
at a previous company, we used to use the jalopy code formatter with eclipse. That would add javadoc to all the methods including private.
It made life difficult to document setters and getters. But what the heck. You have to do it -- you do it. That made me learn some macro functionality with XEmacs :-) You can automate it even further by writing a java parser and commenter like ANTLR creator did several years ago :-)
currently, I document all public methods and anything more than 10 lines.
You can run javadoc against code that does not have javadoc comments and it will produce fairly useable javadocs if you give thoughtful names to your methods and parameters.
I try to at the very least document every public and interface property and method, so that people calling into my code know what things are. I also try to comment as much as possible in line as well for maintenance sake. Even 'personal' projects I do on my own time just for myself, I try to javadoc just because I might shelf it for a year and come back to it later.
Assumed in all the answers so far is that the comments will be good comments. As we all know that is not always the case, sometimes they are even incorrect. If you have to read the code to determine its intent, boundaries, and expected error behavior then the comment is lacking. For example, is the method thread safe, can any arg be null, can it return null, etc. Comments should be part of any code reviews.
This may be even more important for private methods since a maintainer of the code base will have to contend with issues that an API user will not.
Perhaps IDEs should have a feature that allows the use of a documenting form so that the developer can check off various properties that are important and applicable for the current method.