Yes everything. Once you've finished this post, you will be a Comment and Javadoc guru. Woo hoo!
Comments are pretty straight forward and pretty much everyone knows what they are and how they work. Javadocs on the other hand are not so well known. On my university course in computer science, I was taught what a Javadoc was, but I was never expected to create one! Only after seeing them in a real world application did I realise their importance. (Plus they are well cool and easy to make).
Your Guide to Comments:
What is a comment?
Comments are the part of your code that the compiler does not parse. In other words, comments are not really "in" your program once it's run. There are implementation comments, which ill be explaining first, and documentation comments, which are used to create Javadocs - comments exported into html format to document your code and help others who don't have access to the source code to understand the specification of your code (Like an API).
Why comment?
Comments can be used to explain your code. Either so you can understand it (trust me, you will forget what that method was meant to do), or so another person can understand it. In big projects it is highly recommended to comment your code so that other programmers can understand whats going on without having to dig through it.
Comments can also be used in debugging and testing your code. I always temporarily comment out sections of code to test to see if its the reason I'm getting errors, you can also comment out code that prints out useful run time information. When you need extra information on the contents of an array for example, uncomment out the print statements.
Finally comments can be used to populate your Javadoc. Ill explain what that is later.
Types of implementation comments:
End-of-line comments: An end of line comment "comments" out the whole line after a double forward slash.
So:
Notice that the print statement is commented out. If I needed to know what was in the first element of someArray, I would delete the end-of-line comment!
Single line comments: I actually prefer this type of comment over the end-of-line comment. With this you specify the start and end of your comment. This gives greater control over what you want commented. It starts with /* and ends with */ anything in between is a comment.
So:
They are useful for describing what lines of code do. For example I use them with if statements like so:
Block comments: If your comment is long, or covers more then one line. (you might be summarizing a method, data structure or algorithm) then you will need to use a block comment.
example:
Javadocs - Documentation Comments:
Javadocs or Doc comments enable developers to easily document their code. Most IDE's can automatically generate Javdoc html by parsing through your code and interpreting the doc comments. Doc comments describe Java classes, interfaces, constructors, methods, and fields. Each doc comment is set inside the comment delimiters
/**
* Example class provides...
*/
public class Example(){ ...
If you need to have both a Javadoc and a comment explaining the method (one for documentation the other for development) then you should position the Javadoc comment first, then followed by a block comment. Also please remember that doc comments are associated with what immediately follows it (except other comments) and so you cannot write a doc comment after or inside a method declaration!
Now there are certain tags you can use to better document your code. If you are using Eclipse it will create some of the basic ones for you automatically. Just type /** and press enter before a method, class or interface and watch as it inputs the basic outline of your doc. Here are the most useful tags that I use:
@param Give the parameters (inputs) of classes, interfaces, methods or constructors
@return Give the return values of non void methods
@author The author of the class or interface
@see Links to relevant classes
I also use the {@link URL} tag while summarising to link to the class I'm talking about.
To be honest the best way to get used to using Javadocs is to practice creating them in every program you write. Fire up Eclipse, write a quick program and try the tags I've mentioned. If your still a little confused on how to organise them, take a look at the links given at the bottom of this post.
Finally I'd like to quickly explain how to export Javadocs using Eclipse:
Bye for now!
Here are some interesting links about comments and Javadocs:
What each comment is:
http://java.sun.com/docs/codeconv/html/CodeConventions.doc4.html
Wikipedia Javadocs:
http://en.wikipedia.org/wiki/Javadoc
Source code example including Javadoc:
http://java.sun.com/docs/codeconv/html/CodeConventions.doc10.html#182
How to write Javadoc comments (official Sun website):
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html
Javadoc Tool homepage:
http://java.sun.com/j2se/javadoc/index.jsp
Comments are pretty straight forward and pretty much everyone knows what they are and how they work. Javadocs on the other hand are not so well known. On my university course in computer science, I was taught what a Javadoc was, but I was never expected to create one! Only after seeing them in a real world application did I realise their importance. (Plus they are well cool and easy to make).
Your Guide to Comments:
What is a comment?
Comments are the part of your code that the compiler does not parse. In other words, comments are not really "in" your program once it's run. There are implementation comments, which ill be explaining first, and documentation comments, which are used to create Javadocs - comments exported into html format to document your code and help others who don't have access to the source code to understand the specification of your code (Like an API).
Why comment?
Comments can be used to explain your code. Either so you can understand it (trust me, you will forget what that method was meant to do), or so another person can understand it. In big projects it is highly recommended to comment your code so that other programmers can understand whats going on without having to dig through it.
Comments can also be used in debugging and testing your code. I always temporarily comment out sections of code to test to see if its the reason I'm getting errors, you can also comment out code that prints out useful run time information. When you need extra information on the contents of an array for example, uncomment out the print statements.
Finally comments can be used to populate your Javadoc. Ill explain what that is later.
Types of implementation comments:
End-of-line comments: An end of line comment "comments" out the whole line after a double forward slash.
So:
// This is an end-of-line comment
// This prints out the first element in the array
// System.out.println(someArray[0]);
Notice that the print statement is commented out. If I needed to know what was in the first element of someArray, I would delete the end-of-line comment!
Single line comments: I actually prefer this type of comment over the end-of-line comment. With this you specify the start and end of your comment. This gives greater control over what you want commented. It starts with /* and ends with */ anything in between is a comment.
So:
/* This is a single line comment */They are useful for describing what lines of code do. For example I use them with if statements like so:
If(a < b){
/* a is less then b */
}else{
/* a is more then b */
}
Of course in this example the comments are not very useful as its not hard figuring out what the if statement is doing. Comments should be precise and give information that is not easily readable from the code.Block comments: If your comment is long, or covers more then one line. (you might be summarizing a method, data structure or algorithm) then you will need to use a block comment.
example:
/*
* This is a block comment
* This is a block comment
* This is a block comment
*/
Javadocs - Documentation Comments:
Javadocs or Doc comments enable developers to easily document their code. Most IDE's can automatically generate Javdoc html by parsing through your code and interpreting the doc comments. Doc comments describe Java classes, interfaces, constructors, methods, and fields. Each doc comment is set inside the comment delimiters
/**...*/, with one comment per class, interface, or member. This comment should appear just before the declaration:/**
* Example class provides...
*/
public class Example(){ ...
If you need to have both a Javadoc and a comment explaining the method (one for documentation the other for development) then you should position the Javadoc comment first, then followed by a block comment. Also please remember that doc comments are associated with what immediately follows it (except other comments) and so you cannot write a doc comment after or inside a method declaration!
Now there are certain tags you can use to better document your code. If you are using Eclipse it will create some of the basic ones for you automatically. Just type /** and press enter before a method, class or interface and watch as it inputs the basic outline of your doc. Here are the most useful tags that I use:
@param Give the parameters (inputs) of classes, interfaces, methods or constructors
@return Give the return values of non void methods
@author The author of the class or interface
@see Links to relevant classes
I also use the {@link URL} tag while summarising to link to the class I'm talking about.
To be honest the best way to get used to using Javadocs is to practice creating them in every program you write. Fire up Eclipse, write a quick program and try the tags I've mentioned. If your still a little confused on how to organise them, take a look at the links given at the bottom of this post.
Finally I'd like to quickly explain how to export Javadocs using Eclipse:
- After creating your program. Go to file
- Click export
- Find Java and open list and select Javadoc then click next
- If your Javadoc command is empty go to step 5, otherwise go to step 6
- Click configure and search for your jdk folder, find javadoc.exe and click open (mine was in C:\Program Files\Java\jdk1.6.0_07\bin)
- Select the packages you want to include in the Javadoc
- Click Finish
- By default it should be saved in your workspace. Go to the doc file and open up the index.html to see your newly created Javadoc!
Bye for now!
Here are some interesting links about comments and Javadocs:
What each comment is:
http://java.sun.com/docs/codeconv/html/CodeConventions.doc4.html
Wikipedia Javadocs:
http://en.wikipedia.org/wiki/Javadoc
Source code example including Javadoc:
http://java.sun.com/docs/codeconv/html/CodeConventions.doc10.html#182
How to write Javadoc comments (official Sun website):
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html
Javadoc Tool homepage:
http://java.sun.com/j2se/javadoc/index.jsp
