I watched this video in its entirety. I found it very interesting how he got his point across.

Guy Steele’s keynote at the 1998 ACM OOPSLA conference on “Growing a Language” discusses the importance of and issues associated with designing a programming language that can be grown by its users.

What is a comment? How do you use comments in Java? When should they be used? If you are wondering you should read on

The Idea

Probably the most important piece of code you can write is a comment. Comments not only make your code more clear to others, it will also help you to remember what you were thinking for future development.

The Solution

A comment is a piece of code that is ignored by the compiler that allows others to understand what is going on. In java there are two ways you can comment your code. You can use the traditional double forward slash like this

//This is a comment

which comments everything to the left of the double forward slashes and ends with a new line. Or the other commonly used comment for commenting multiple is the forward slash asterisk like this:

/**
using this
You can
Comment multiple
Lines
*/ 

It is a common standard to comment every method in a class and include the parameters and return values. The java docs make specific use of this. Lets say we are giving a simple class like the one below:

package helloworld;
public class Hello {
	private String name;
	public hello(String aName) {
		name = aName;
	}

	public String sayHello(){
		Return "Hello, " + name + "!";
	}
}

If this code were well commented it would look like this:

package helloworld;
public class Hello {
	private String name;
	/**
	 * Constructs a Hello object that can greet a person.
	 * @param aName the name of the person who should be addressed.
	*/

	public hello(String aName) {
		name = aName;
	}
	/**
	 * Greet with a "Hello" message.
	 * @return a message containing "Hello" and the name of the person.
	*/
	public String sayHello(){
		Return "Hello, " + name + "!";
	}
}

The first line of a comment should be well formed to give the holistic idea of what that method does. In comments parameters are commented using the @param and return values are commented using @return. If you properly comment your documents, you can use Java’s javadoc utility to create a series of HTML files that document your classes and methods, but javadocs use your comments!