Coding Conventions!

[the_short1]

Well, it seems like lots of ppl dont know the proper code conventions (And yes im guilty to not following all of them myself), but I try to follow them and its a good thing to get into the habit of.

Here is a link I found recently, and I thought I would share
http://java.sun.com/docs/codeconv/

I recomend the .pdf form for ease of reading through the whole thing (vs HTML)

-Kevin

[Aziz]

That being said, kevin, what form brackets do you use?

Sun says the

Java:

public void method() {   //Some code }

is the preferrable way, but many people (including well experienced programmers) use a more, erm, explicit (isn't the exact word but it'll do), way (although it does result in more whitespace):

Java:

public void method() {   //Some code }

While both are organized (as long as you use them correctly!) Is there anything really against the latter one? I've know it makes the code a bit longer, but it's also really readable (and not to mention a hard habit to break). The point is, should the braces convention be strictly to the former way? In you opinion?

[[Gandalf]]

It's simply a matter of the preference of the community. The Java people prefered the braces kept on the same line and made that the standard. In many other languages, the community settled on putting them on a new line, and that became the convention. They both have merits, so it really comes down to your choice of which to use. What's more imporant than this choice is that you keep a consistent style throughout your code.

[the_short1]

Well said gandalf..

Personally, ive always used the { being on the same line without knowing the coding conventions, and i was glad to read that i was doing it in the right In my opinion, I find it easier to trace back the origin by having less curly braces and brackets to muddle it up..as well, i will use whitespace when needed of course, but overall i like compactness and the prefered method gives me that.

but as for if else statements, ive always used this form...

code:

if (condition == blah){     //code } else{     //code }

I just started adapting to the standard form "}else{"and its not bad, keeps related if else more "together".. so i like it...thing im most guilty of is my comment structure sucks, and i tend to have a lot of messy tailing comments...i dont like putting them on there own line...What about you, what conventions do you directly follow / guilty of not doing right?

edit: they discourage having no curly braces if only 1 action per if statement, but its just soo excessive to have them if you have several if statements with only 1 action line..... but i guess switch case is a better alternative then...

[Aziz]

I still like to use the braces on a new line. I've just been used to it and I'm usually over-organized. But I like it because I can see my code block right away. I used to use the on-line if statements with no brackets, but after reading that article, I don't. They're point is really good. If you add another line in after testing, or especially a few weeks/months down the road, it's not going to work the way you want it, especially in places where it's not evident (algorithms and background calculations). Find an error in drawing is pretty easy, but it can be hard to trace in the debugging process.

In really short if's i put the statement, braces and code all on one line:

Java:

if (*expression*) { statement; } else if (*expression*) { statement; } else { statement; }

or in my current project something like (more organized):

Java:

public void actionPerformed(ActionEvent e)     {         String cmd = e.getActionCommand();                 //Handle commands         if (cmd.equals(IN)) // Punch In button         { actionIn(); }         else if (cmd.equals(OUT)) //Punch Out button         { actionOut(); }         else if (cmd.equals(EDIT)) //Edit button         { actionEdit(); }         else if (cmd.equals(DEL)) //Delete button         { actionDelete(); }         else if (cmd.equals(CALC)) //Calculate button         { actionCalc(); }         else if (cmd.equals(SAVE)) //Save button         { actionSave(); }         else if (cmd.equals(PRINT)) //Print paystub button         { actionPrint(); }     }

or for try/catch blocks, when you don't have to catch anything.

Java:

try {    //some code } catch (Exception e) {}

Really, code conventions IMO are guidelines, not rules. If it's still readable, then it should be good. Shortcuts like this can improve readability, if used right. A bad example:

Java:

if (a == 5 || a == 3 || a == 7 || name.equals("Joe") || !keepGoing) {a = b; name = "Fudgecake"; b++; System.out.println(name + a/b);}

A good idea would probably show it to a fellow programmer and see if they can understand. You see so many posts here with somebody trying to get help and the first reply is "What's this *code snippet* supposed to be?". I think somebody should write a walk-through tutorial on right proper code.

[wtd]

Understanding why the guidelines are what they are is about a million times better than just blindly following them.

[wtd]

Oh and just say no!

code:

if (cmd.equals(IN)) // Punch In button         { actionIn(); }         else if (cmd.equals(OUT)) //Punch Out button         { actionOut(); }         else if (cmd.equals(EDIT)) //Edit button         { actionEdit(); }         else if (cmd.equals(DEL)) //Delete button         { actionDelete(); }         else if (cmd.equals(CALC)) //Calculate button         { actionCalc(); }         else if (cmd.equals(SAVE)) //Save button         { actionSave(); }         else if (cmd.equals(PRINT)) //Print paystub button         { actionPrint(); }

By the way, is there some reason that you don't have action listeners on each widget, that would remove the need for this kind of dispatch mechanism?

[Aziz]

wtd wrote:

Understanding why the guidelines are what they are is about a million times better than just blindly following them.

Very true, such as the if statement conventions, always using braces. I'm a sinner, though, sometimes, as I'm lazy. I usually (well I make a point to) go back and fix up my programs after they're done and I see what needs changing.

wtd wrote:

By the way, is there some reason that you don't have action listeners on each widget, that would remove the need for this kind of dispatch mechanism?

Yes. The reason would be that I haven't looked into it yet and that I referred to my last project for reference, as I haven't touched Java, let alone SWING, in a bit. I'm going to check it out and see what to do with it right now, actually. Thanks, I probably would've left it that way

[wtd]

I find that Java as a language (leaving the VM and library out of the debate) is not terribly powerful, but anonymous inner classes are one of the better things it provides.

[Aziz]

wtd, what exactly do you mean? This is what I'm doing right now:

I'm only using buttons, no toolbar, so I don't think I'll benefit from using an Action. Here's the buttons:

Java:

inButton = makeButton("Punch In", IN);         outButton = makeButton("Punch Out", OUT);         editButton = makeButton("Edit", EDIT);         deleteButton = makeButton("Delete Last", DEL);                 calcButton = makeButton("Calculate", CALC);         saveButton = makeButton("Save", SAVE);         printButton = makeButton("Print Paystub", PRINT);

and the makeButton() method:

Java:

private JButton makeButton(String text, String actionCommand)     {         JButton b = new JButton(text);         b.addActionListener(this);         b.setActionCommand(actionCommand);                 return b;     }

and then the actionPerformed() method from ActionListener interface:

Java:

public void actionPerformed(ActionEvent e)     {         String cmd = e.getActionCommand();                 //Handle commands         if (cmd.equals(IN)) // Punch In button         { actionIn(); }         else if (cmd.equals(OUT)) //Punch Out button         { actionOut(); }         else if (cmd.equals(EDIT)) //Edit button         { actionEdit(); }         else if (cmd.equals(DEL)) //Delete button         { actionDelete(); }         else if (cmd.equals(CALC)) //Calculate button         { actionCalc(); }         else if (cmd.equals(SAVE)) //Save button         { actionSave(); }         else if (cmd.equals(PRINT)) //Print paystub button         { actionPrint(); }     }

All the sources I've checked (including The Java Tutorial and the Java Almanac) do it this way, or using an source = e.getSource() method, unless that's what you mean? Thanks wtd.

[wtd]

code:

JButton inButton = new JButton("Punch In"); inButton.addActionListener(new ActionListener() {     public void actionPerformed(ActionEvent e) {         actionIn();     } });

Of course, there's a good change the code in actionIn should just be moved into the inner class, but I'm just working with what's provided.

Or in Scala, where it looks nicer.

code:

val inButton = new JButton("Punch In") with ActionListener {     def actionPerformed(e: ActionEvent) = actionIn }

[Aziz]

So I shouldn't use separate methods for actions, just all the code inside the addActionListener() bit? I have another question but I'll post a new topic, to avoid spamming this post (what happened to 'code conventions tutorial' )

[the_short1]

Aziz wrote:

So I shouldn't use separate methods for actions, just all the code inside the addActionListener() bit? I have another question but I'll post a new topic, to avoid spamming this post (what happened to 'code conventions tutorial' )

yea .. good idea i acually replied to your question before wtd posted, but i didnt hit the post button until 5minutes after he posted so i had to delete it .. lol.... Yea .. .code convetions... about that...

[Aziz]

In topic, what about commenting? Shouldn't there be at least some standard or convention, even a general tip, about commenting? Like, when to use the different types: one-line, block, and end-of-line, for example, and when not to use commenting at all.

[wtd]

There are good conventions for this.

The first guideline: Don't use comments to say something that the code already says. It is the responsibility of the person reading your code to know the language the code is written in. Do not coddle readers.

Comments should, if necessary, explain the intent of a piece of code. "Why are you incrementing that accumulator variable?" That said, do not comment common idioms. Again, you are not responsible if the person reading your code is an idiot. If they are, and for some reason it is your problem, then make sure they understand those idioms in general, before reading your code.

Place comments above the code they refer to. Not after or beside. Before.

Use line comments when you only want one line. Use multi-line comments when you need multiple lines of comment.

Do not let a comment stretch more than 80 characters wide.

Use documentation comments when you want an explanation to appear in documentation.