Thread: Commenting your code: RIGHT or WRONG way?

Javadoc is a MUST. You should always put javadocs in front of public methods and class declarations. There are also some valid arguments for putting them on private class variables and private methods. Javadocs are important because you can use them to automatically generate the API documents (like the ones you see on oracle's APIs), and you can use them to provide other developers with information when they are using the method or variable with one of those auto-complete suggestion popups that popular IDEs have.
Single line statements for permanent commenting should only be used if something particularly complex is happening in the code. If it is simple code that a competent developer should be able to trace and understand by looking at it, it should not be heavily commented. But if it is complex and you have many loops and condition statements, a few comments here and there can be very helpful to understand what the code does.
Notice how I said "permanent" comments. There are also temporary comments which are tagged. These tags are used to indicate future plans to the code, and most IDEs will notice them and list them for you from a project level so you can find them easily.

Here is an example of the javadoc and tagged comments:

/**
 * This class is an example, and this is a class javadoc. 
 * Notice the double stars on the first line. A single star is a comment block.
 * A double star is a javadoc.
 *
 * @author John Smith
 * @date 1/9/2013
 */
public class Foo {
 
	/**
	 * This is a variable javadoc.
	 */
	public int var;
 
	/**
	 * This is a method javadoc.
	 * This method returns an integer.
	 * 
	 * @return the integer 5
	 */
	public int returnSomeInt() {
		return 5;
		// TODO: change to return 1. The todo tag indicates future plans (notice all capitals)
	}
 
	/**
	 * This method is just here to show the other tags
	 */
	public void someOtherMethod() {
		// FIXME: This tag is used to indicate a known bug which should be fixed. You should briefly state the problem and a solution if you have one planned
		// XXX: This is just a general notification for the developer, which are neither todos or fixmes
	}
}

So my development process actually starts with comments. I begin by describing what it is I need to do and roughly how it should get done. Filling in the actual code comes second.

Adding extra comments and modifying the base comments comes as needed. The million dollar question is does this new comment make my code more clear to others months or even years from now?

There are such things as wasted comments. In general I find these comments to be those which merely repeat what a single isolated line of code does:

// some wasteful comments:
 
// increment i
++i;
// add a and b
c = a + b;
 
// compute the dot product of v1 and v2
val = v1.dot(v2);
 
// is some_condition true?
if(some_condition == true)
{
}
// otherwise,
else
{
}

In general comments should explain the context, or if you have a complicated expression explaining it in plain English may also be warranted. Here are some reasonable comments (note: even though the comments may be reasonable, the actual code isn't necessarily good):

// compute the dot product of v1 and v2
val = v1.x * v2.x + v1.y * v2.y + v1.z * v2.z;
 
// swap A and B
int tmp = A;
A = B;
B = tmp;
 
// Creates a new JButton with some text using reflection
JButton.class.getConstructor(String.class).newInstance("A Button");

Here's an example of how I might develop a sort method.

sort_start is where I would start from, writing out comments and having very minimal actual code. sort_impl is the finished implementation with appropriate comments. Yes, I am missing all of the Javadocs. Ignore that and follow Aussiemcgr's advice on always having Javadoc.

public void sort_start(int[] data)
{
    // A simple selection sort.
    // for every index in data:
        // find the max value between [index, length)
        // swap the max value with the value at index
}
 
public void sort_impl(int[] data)
{
    // A simple selection sort.
    for(int i = 0; i < data.length; ++i)
    {
        // find the max value between [index, length)
        int max_idx = i;
        for(int j = i; j < data.length; ++j)
        {
            if(data[j] > data[max_idx])
            {
                // found a new max value
                max_idx = j;
            }
        }
        // swap the max value with the value at index
        int tmp = data[j];
        data[j] = data[max_idx];
        data[max_idx] = tmp;
}

I personally hate useless comments or comments which state the obvious. If your comments look like these:

/**
* Sets the name of this object to someName.
*/
public void setName(String someName) {
}

Then better remove the comment entirely to save some place. This is really not going to help anybody.

The comment itself if poorly written. But this comment is actually a javadoc, so it is important to include. In fact, it should also have a param tag which describes the purpose of the someName variable. Javadocs can sometimes feel unnecessary for setters and getters, but it is a coding standard because it allows the generation of the API. A developer who is using an API should not have to attempt to guess the purpose of a method, or trace a method, to understand what it does. That information should be clearly stated with javadocs. You can view all the javadoc standards here (there is a lot): How to Write Doc Comments for the Javadoc Tool
Your second example, is a bit better, but you left out the javadoc tags, which makes the javadocs format better when they are generated:

	/**
	 * Returns the important data that is somehow connected to the given integer and string arguments.
	 * 
	 * @param anInteger should be within the range [0, getSize()) otherwise an {@link IndexOutOfBoundsException} will be thrown
	 * @param someParam should not be null, otherwise a {@link NullPointerException} will be thrown
	 * 
	 * @return a List which contains the important data. The list can be null, unless the method {@link #initialize()} has been invoked beforehand.
	 */
	public List<?> getImportantData(int anInteger, String someParam) {
	}

Also, with regard to HelloWorld's example. This is a good example where you could also include the TODO tag, since the comments are indicating future plans:

public void sort_start(int[] data)
{
    // TODO: A simple selection sort.
    // for every index in data:
        // find the max value between [index, length)
        // swap the max value with the value at index
}