Style guide: Source Code
The code formatting tools available in modern IDEs are nothing short of miraculous.
Eclipse in particular has an outstanding code formatter that is highly configurable. This encourages people to tinker and have their code be just the way they like it. That’s a Good Thing (tm), but it plays havoc when it comes time to create diffs as patches to commit to the version control system. So we need to share a code format convention.
Java conventions, mostly
We ended up adopting what Eclipse termed the “Java conventions [builtin]”,
with four modifications. Notably, this default Java style is set to convert
tabs to 4 spaces. I personally prefer
\t characters, but it makes a mess
when looking at diffs or raw files because the terminal expands tabs to 8. So
I’ll buy this one — better that your code looks correct at all times.
The modifications are:
The opening brace on a Class statement is on its own line, not on the same line as the declaration. This is largely to provide some visual distinctness to the nested interfaces that contain our signal handler callbacks. Otherwise, they look too much like methods and it’s very confusing to read.
The code width is 105 characters. The default of 80 causes so much wrapping to render it unreadable - especially in things like the Constant Object declarations in Enums and Flags.
Comment with is 78 characters. The default of 80 would be fine, except that when you view the changes to a file with the version control tool’s diff command, the
-character push the line out past the to the 80 character mark, and that’s no good in the standard 80 character wide terminal where you ran the command in the first place.
empty methods have both braces on the same line. We’ve got quite a number of private constructors which are empty and just serve to prevent the class showing up as an option when doing
. An empty method with a blank line in it appears to the eye to be unfinished, and so we want to avoid that distraction.
Your patches have a much better chance of being accepted if they produce clean diffs, and that’s more likely to happen if you stick to these rules. If you’re using Eclipse, you will find “The java-gnome Style” pre-configured in the .settings/ directory. Just hitting Format should do the trick.
(Come on Sun boys and girls! Make me believe that NetBeans is better…)
TODO: coding practises. Not really too much to talk about here.
Originally written by Andrew Cowie 27 Nov 06. Last modified 9 Dec 06.