Coding Conventions!

[Aziz]

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?

[wtd]

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]

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]

Aziz wrote:

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]

code:

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

Place those comments above the code they relate to.