Coding Style - The Rest Of It

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!
  For example, HTMLDocument should be named HtmlDocument.
  CSSParser should be 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.
  Use
  

  
  private boolean foo;
  private Bar bar;
  

  
  instead of
  

  
  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"
  approach.
  





• Use 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
  parameter newFoo or 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.