WARNING: This blog entry was imported from my old blog on blogs.sun.com (which used different blogging software), so formatting and links may not be correct.
There are several coding style documents. The primary one is probably the JDK style,
documented here. The problem with that document, and others like it,
is that they leave a lot out.
I found some other useful coding style
documents, but I disagree vehemently with some of their rules (like open braces on a separate line,
and underscore suffixes and fields, and indentation level 2) so instead I will present
my own delta from the "official" JDK style:
So, with the following I'd like to put a stake in the ground, and describe my own
style preferences as additional rules to be added to the JDK style.
I should point out that these aren't rules I've invented - they are rules I've
learned from either discussing with, or reading code written by, developers I admire.
So, without further ado, here are my additional rules:
- Never use Tabs. Some people like tab characters because it's easy to
jump back and forth full indentation levels by just pressing arrow left and right over
these. However, this benefit does not nearly make up for the disadvantages: different
tools assume different tab sizes, and things get really messy when you have files with
spaces in some places and tabs in others. Just don't do it.
This issue has been around for a long time, and I figured the style guide would
discuss it, but they left it an open issue. Cowards! :-)
Never capitalize Acronyms. Yes, unlearn everything your English teacher told you
about acronyms. Remember, camel cased program identifiers aren't English words anyway!
HTMLDocumentshould be named
CssParser. This makes the code easier to
read and easier to visually scan. Plus it's prettier.
Don't use underscores in variable names. I didn't say Never, since there's one
exception: for constants, the constant should be fully upper cased, and words separated
with an underscore, e.g. MAX_VALUE or INITIAL_VELOCITY. But never ever create variable
names like "max_count" or worse yet, "_count".
- Don't use Hungarian Notation. This is where you prefix variable names
to tell you whether these methods are locals or class fields, etc. This makes the
code less readable (even if you can infer more state from studying the code).
And uglier. Ugly is bad.
Don't put in obvious initialization. This is not a big deal, but again
in the interest of readable code: don't state the obvious. When you're declaring
class fields, there's no need to assign booleans to false, references to null, etc.
private boolean foo;
private Bar bar;
private boolean foo = false;
private Bar bar = null;
- Don't add your initials in comments. Some developers like to leave
their initials next to comments, e.g. // TN Handle abnormal exit here. People
from Borland seem especially fond of this. I don't think this is a good habit.
The comment should be self-descriptive, regardless of who added it. If it represents
an action that needs to be taken, then add the token "reserved" for this: TODO.
- Don't use recursion where simple iteration would work. I recently
came across a code fragment that was simply walking up the parent chain to look
for a particular ancestor. This was done using recursion! This should be done
with simple iteration. Iteration in this case is clearer than the "mathematical"
this.foo = foo;for construction field initialization. If your class
has a property
foo, then name your constructor parameter name the same thing, and
initialize it using the this-pattern shown. Don't use other variations like naming the
newFooor worse yet, something involving an underscore in the parameter name!
- Write debuggable code!. I've seen many people argue that you should use the ternary
operator (a ? b : c) instead of if-then-else constructs. While the ? operator certainly makes
for more compact code, this code is often hard to debug, because you cannot easily set breakpoints
on one condition and not the other, and you cannot easily step to see which condition is taken.
This is an "issue to consider" more than a "rule to follow" since there are tradeoffs, and
I use both forms, depending on the context.