Programming C, C++, Java, PHP, Ruby, Turing, VB
Computer Science Canada 
Programming C, C++, Java, PHP, Ruby, Turing, VB  

Username:   Password: 
 RegisterRegister   
 Coding Conventions!
Index -> Programming, Java -> Java Tutorials
Goto page Previous  1, 2
View previous topic Printable versionDownload TopicRate TopicSubscribe to this topicPrivate MessagesRefresh page View next topic
Author Message
Aziz




PostPosted: Sun Jul 23, 2006 10:01 pm   Post subject: (No subject)

Are end-of-line comments always a no-no? A read an article that said never use them, but what about where it simply describes something in a list of said somethings.

code:
//Add components to frame
frame.add(topPane);      //Top panel, contains header title.
frame.add(middlePane);   //The middle panel, contains forms.
frame.add(bottomPane);   //The bottom panel, contains status bar.


Does this take away from it? I haven't been doing it much, but I know what I'm doing, and I don't really look at other peoples' code too much. You have, wtd, is it a pain in the ass when these comment are around?
Sponsor
Sponsor
Sponsor
sponsor
wtd




PostPosted: Sun Jul 23, 2006 10:18 pm   Post subject: (No subject)

Your first comment is utterly unnecessary. From the code (if the entire file were shown) it is easy to ascertain the type of "frame" and the arguments passed to add. It then becomes easy to determine what these methods do by looking at the documentation.

Further, any programmer with any decent level of Java GUI experience will not even need to consult the docs to figure that out.

If you wish to document what topPane and company are for, you should do that when you declare those variables.

Perhaps you should also name those variables to indicate what they are for, rather than where they will be placed.
Aziz




PostPosted: Mon Jul 24, 2006 8:03 am   Post subject: (No subject)

Smile You make good points, wtd. In fact, I have started naming the panels by use. such as clockPane, listPane, etc. I like your way of thinking. I'm still use to commenting *everything* from my compsci class.
the_short1




PostPosted: Mon Jul 24, 2006 6:54 pm   Post subject: (No subject)

Aziz wrote:
Smile You make good points, wtd. In fact, I have started naming the panels by use. such as clockPane, listPane, etc. I like your way of thinking. I'm still use to commenting *everything* from my compsci class.


Yea, ditto on that one, im used to commenting practically everyline, it became habbit as i type a line of code type the comment after it.. and before line comments would double the length of the code so i always used trailling..

The convention for commenting, putting a /* Comment */ the line before/first line inside any if statement/for loop/method etc if needed, im finding is much more clearer, and neater then trailing comments.

Wtd, you mentioned comment it where you declared it, well im curious to the form that YOU use for commenting variables at the top of your code.

Java Convention mentioned if trailling comments are used, to align them with other variables. or at least keep the majority of them together.

eg:
int counter = 0; - - - - - - - - - - - // Counter for array filling
int thatOtherLongVariable = 0; // Im a useless variable

Do you think it would be better to initialize on a seperate line to avoid mess>?

Edit: dashes just used to keep the spaces there
wtd




PostPosted: Mon Jul 24, 2006 10:06 pm   Post subject: (No subject)

code:
int counter = 0; // Counter for array filling
int thatOtherLongVariable = 0; // Im a useless variable


Place those comments above the code they relate to.
Display posts from previous:   
   Index -> Programming, Java -> Java Tutorials
View previous topic Tell A FriendPrintable versionDownload TopicRate TopicSubscribe to this topicPrivate MessagesRefresh page View next topic

Page 2 of 2  [ 20 Posts ]
Goto page Previous  1, 2
Jump to:   


Style:  
Search: