Did I comment this code correctly?

[Vinx]

I'm starting to get into the Midi library in Java. Sorry if I haven't been posting on the forums a whole lot. I don't really think I should be contributing yet, as I'm fairly new to Java myself.

This code was in my book, not commented. I wanted to make sure I'm commenting the code in a understandable manner.

Also, I've been using Google but I haven't been able to find any standard format for commenting code in Java, so I guessed.

import javax.sound.midi.*; // Import Midi

public class MiniMusicCmdLine { // create public class MiniMusicCmdLine
	
	public static void main(String[] args) { // start main
		MiniMusicCmdLine mini = new MiniMusicCmdLine(); // Create a MinimusicCmdLine object
		if (args.length < 2) { // if there is less than 2 arguments
			System.out.println("Don't forget the instrument and note args."); // then print requesting arguments
		} else { // else if there are 2+ arguments
			int instrument = Integer.parseInt(args[0]); // declare instrument, arg row 1 in array
			int note = Integer.parseInt(args[1]); // declare arg note, arg row 2 in array
			mini.play(instrument, note); // play
		} // end else statement
	} // end main
	
	public void play(int instrument, int note) { // declare the command play, possible args instrument and note
		
		try { // try
			Sequencer player = MidiSystem.getSequencer(); // declare sequencer player, player is sequencer
			player.open(); // open player
			Sequence seq = new Sequence(Sequence.PPQ, 4); // declare sequence seq, 4
			Track track = seq.createTrack(); // create track
			
			MidiEvent event = null; // create MidiEvent event, value is null
			
			ShortMessage first = new ShortMessage(); // declare ShortMessage first
			first.setMessage(192, 1, instrument, 0); // set message of first to 192, 1, instrument, 0
			MidiEvent changeInstrument = new MidiEvent(first, 1); //  create MidiEvent changeInstrument; first, 1
			track.add(changeInstrument); // add changeInstrument to track
			
			ShortMessage a = new ShortMessage(); // declare ShortMessage a
			a.setMessage(144, 1, note, 100); // setMessage a 144, 1 , note , 100
			MidiEvent noteOn = new MidiEvent(a, 1);  //  create MidiEvent noteOn
			track.add(noteOn); // add noteOn to track
			
			ShortMessage b = new ShortMessage(); //  declare ShortMessage b
			b.setMessage(128, 1, note, 100); // set message of b; 128, 1, note, 100
			MidiEvent noteOff = new MidiEvent(b, 16); // create new MidiEvent noteOff; b, 16
			track.add(noteOff); // add noteOff to track
			player.setSequence(seq); // setSequence of seq
			player.start(); // start the player
			} catch (Exception ex) { //end try,  catch Exceptions arg ex
			ex.printStackTrace(); // printStackTrace
		} // end Catch
	} // end  play
	
	
} // end class

Original code created by the team of Head First Java. It's available publicly on their website, so I believe it's alright if I post this.

[Fubarable]

This code was in my book, not commented. I wanted to make sure I'm commenting the code in a understandable manner.

I think that you've grossly over-commented the code and that your comments distract from the code rather than increase understanding.

For instance,

import javax.sound.midi.*; // Import Midi

What does this add?

public class MiniMusicCmdLine { // create public class MiniMusicCmdLine

ditto

	
	public static void main(String[] args) { // start main

ditto

		MiniMusicCmdLine mini = new MiniMusicCmdLine(); // Create a MinimusicCmdLine object

ditto

etc....

[doWhile]

The javadoc tool has standard commenting formats (see How to Write Doc Comments for the Javadoc Tool ). This standard helps you use the javadoc tool to write your own higher level API for fields, methods, classes, and packages.

[Vinx]

I think that you've grossly over-commented the code and that your comments distract from the code rather than increase understanding.

For instance, [.....]

Alright, thank you.

The javadoc tool has standard commenting formats (see How to Write Doc Comments for the Javadoc Tool ). This standard helps you use the javadoc tool to write your own higher level API for fields, methods, classes, and packages.

I'll definitely look into this, much appreciated.

[doWhile]

Forgot to add this other reference to my last post - the java code conventions also touches on the subject as well: Code Conventions for the Java Programming Language

[kjkrum]

Most of your comments are redundant, in that they just tell you what the code does. That adds nothing to what someone can tell from just reading the code. Instead of comments saying what the code does, write comments that explain why the code does what it does, especially where it might not be clear. I'm the only person maintaining most of my own code, but I pepper it with comments because after a few months, even I will not remember why I did something a certain way.

Some examples of comments in a project I'm working on:

// create a standalone LoginOptions because we don't have a db yet

// TODO: understand why removing this causes deadlock

// this is kind of hackish, but it keeps the scroll pane from widening itself

catch(IOException ex) {
	// not this class's problem
}

public void keyPressed(KeyEvent e) {
	// don't care		
}

SocketChannel channel;	// note: hides NetworkManager.channel

catch(UnderflowException e) {
	// this is normal...
	if(dataBuffer.position() == 0 && dataBuffer.length() == dataBuffer.capacity()) {
		// ...but if *this* ever happens, something
		// is seriously wrong with the lexer rules
		throw e;
	}
}