Results 1 to 6 of 6
Like Tree1Likes
  • 1 Post By kjkrum

Thread: Did I comment this code correctly?

  1. #1
    Vinx is offline Member
    Join Date
    May 2012
    Location
    USA
    Posts
    38
    Rep Power
    0

    Default Did I comment this code correctly?

    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.



    Java Code:
    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.

  2. #2
    Fubarable's Avatar
    Fubarable is offline Moderator
    Join Date
    Jun 2008
    Posts
    19,316
    Blog Entries
    1
    Rep Power
    26

    Default Re: Did I comment this code correctly?

    Quote Originally Posted by Vinx View Post
    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,

    Java Code:
    import javax.sound.midi.*; // Import Midi
    What does this add?

    Java Code:
    public class MiniMusicCmdLine { // create public class MiniMusicCmdLine
    ditto

    Java Code:
    	
    	public static void main(String[] args) { // start main
    ditto

    Java Code:
    		MiniMusicCmdLine mini = new MiniMusicCmdLine(); // Create a MinimusicCmdLine object
    ditto

    etc....

  3. #3
    doWhile is offline Moderator
    Join Date
    Jul 2010
    Location
    California
    Posts
    1,642
    Rep Power
    7

    Default Re: Did I comment this code correctly?

    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.

  4. #4
    Vinx is offline Member
    Join Date
    May 2012
    Location
    USA
    Posts
    38
    Rep Power
    0

    Default Re: Did I comment this code correctly?

    Quote Originally Posted by Fubarable View Post
    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.


    Quote Originally Posted by doWhile View Post
    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.

  5. #5
    doWhile is offline Moderator
    Join Date
    Jul 2010
    Location
    California
    Posts
    1,642
    Rep Power
    7

    Default Re: Did I comment this code correctly?

    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

  6. #6
    kjkrum's Avatar
    kjkrum is offline Senior Member
    Join Date
    Apr 2011
    Location
    Tucson, AZ
    Posts
    1,060
    Rep Power
    6

    Default Re: Did I comment this code correctly?

    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:

    Java Code:
    // 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;
    	}
    }
    Fubarable likes this.
    Get in the habit of using standard Java naming conventions!

Similar Threads

  1. Sorting code not working correctly
    By jubbiejub in forum New To Java
    Replies: 3
    Last Post: 05-01-2012, 01:28 AM
  2. Why isn't this snipet of code working correctly
    By josho493 in forum New To Java
    Replies: 4
    Last Post: 04-19-2012, 09:59 AM
  3. Code completion not updating correctly
    By kspn in forum NetBeans
    Replies: 1
    Last Post: 02-22-2011, 10:28 PM
  4. So when it says to comment your code..?
    By xhoneyskye in forum New To Java
    Replies: 6
    Last Post: 01-27-2010, 09:26 AM
  5. About Comment By Using SAX
    By tapas in forum XML
    Replies: 1
    Last Post: 01-24-2008, 05:29 AM

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •