[Mulgara-dev] Code format standards

[Paul Gearon]

Hi all,

While going through the code recently, I've noticed some oddities in  
the formatting of the code.  Back with TKS/Kowari there was a  
published document on this, but we haven't put anything up in Mulgara  
yet.  I think I'm going to have to do something about it.

The previous "standard" wasn't too strict, but it did ask a few things.

The points to note were:

1.  Use braces on the same line, or on separate lines.  eg. an if/ 
else may be either:
     if (test) {
     } else {
     }
or
     if (test)
     {
     }
     else
     {
     }

Same goes for other blocks, like loops and try/catch.  Personally, I  
hate the second format, but we couldn't gain consensus on this issue,  
and we'd rather that developers feel comfortable writing their code,  
so we allowed for either.  However, we do insist that styles are NOT  
mixed.  Thus, the following is not accepted:
     if (test) {
     }
     else {
     }

This is for consistency.  When braces are on their own lines, then a  
close brace still means that you should look to the next line to see  
if there is an else or a catch.  But the mixed style can catch people  
out, which is why we don't allow it.

2.  No extra spaces inside parentheses.  The only spaces we like are  
after commas and semicolons, and around binary operators (like +).   
We also suggest spaces after keywords (outside of parentheses  
obviously), and no spaces after casts or function names.  This is  
mostly to stick to the Sun coding standards.

3.  No one uses 80 character displays anymore.  There is no need to  
wrap at this point.  Don't go stupid with line width, but 120 should  
be fine.  Line 571 of RemoteAnswerWrapperAnswer.java demonstrates  
what I'm talking about:
       throw new TuplesException("Unable to get column \"" +  
columnName + "\"",
                                 e);

4.  Unless you're actively making significant changes to a file,  
don't go updating someone else's format.  Keep files consistent.   
This means don't change a file when you're adding one or two lines,  
and if you're changing enough to start making format changes, then  
change the whole file.

---
That's not everything, but I just needed to look in 2 files to  
discover all of them violated.  I'm tired, so it kind of annoyed me.   
Point 2 doesn't bother me very much, but point 1 is a big one.  Point  
4 particularly annoyed me, as I was seeing wholesale formatting  
changes (to an unacceptable format) of code that I'd written, and I  
can't see any significant changes since I wrote it.

I'm guessing that the culprits aren't here now (maybe it was NGC?),  
but since we have new developers looking at the code I thought I'd  
better mention it so no one can say they didn't know.  I'll find the  
code formatting document, or write a new one, and put it on  
mulgara.org.  I'm also going to find the egregious examples and  
change them back (in violation of rule 4, but rule 4 presumed that  
things wouldn't get this bad).

Regards,
Paul

P.S. What does one do when you're the only one watching your kids and  
you want to watch your first Superbowl?  The kids aren't really  
interested in watching football.  :-)