Stylistic Question: Use of White Space

Question

I have a particularly stupid insecurity about the aesthetics of my code... my use of white space is, frankly, awkward. My code looks like a geek dancing; not quite frightening, but awkward enough that you feel bad staring, yet can't look away.

I'm just never sure when I should leave a blank line or use an end of line comment instead of an above line comment. I prefer to comment above my code, but sometimes it seems strange to break the flow for a three word comment. Sometimes throwing an empty line before and after a block of code is like putting a speed bump in an otherwise smooth section of code. For instance, in a nested loop separating a three or four line block of code in the center almost nullifies the visual effect of indentation (I've noticed K&R bracers are less prone to this problem than Allman/BSD/GNU styles).

My personal preference is dense code with very few "speed bumps" except between functions/methods/comment blocks. For tricky sections of code, I like to leave a large comment block telling you what I'm about to do and why, followed by a few 'marker' comments in that code section. Unfortunately, I've found that some other people generally enjoy generous vertical white space. On one hand I could have a higher information density that some others don't think flows very well, and on the other hand I could have a better flowing code base at the cost of a lower signal to noise ratio.

I know this is such a petty, stupid thing, but it's something I really want to work on as I improve the rest of my skill set.

Would anyone be willing to offer some hints? What do you consider to be well flowing code and where is it appropriate to use vertical white space? Any thoughts on end of line commenting for two or three words comments?

Thanks!

P.S. Here's a method from a code base I've been working on. Not my best, but not my worst by far.

/**  
 * TODO Clean this up a bit.  Nothing glaringly wrong, just a little messy.  
 * Packs all of the Options, correctly ordered, in a CommandThread for executing.  
 */  
public CommandThread[] generateCommands() throws Exception
 {  
  OptionConstants[] notRegular = {OptionConstants.bucket, OptionConstants.fileLocation, OptionConstants.test, OptionConstants.executable, OptionConstants.mountLocation};  
  ArrayList<Option> nonRegularOptions = new ArrayList<Option>();  
  CommandLine cLine = new CommandLine(getValue(OptionConstants.executable));  

  for (OptionConstants constant : notRegular)  
   nonRegularOptions.add(getOption(constant));  

  // --test must be first  
  cLine.addOption(getOption(OptionConstants.test));  

  // and the regular options...  
  Option option;  
  for (OptionBox optionBox : optionBoxes.values())  
   {  
    option = optionBox.getOption();  
    if (!nonRegularOptions.contains(option))  
     cLine.addOption(option);  
   }  

  // bucket and fileLocation must be last  
  cLine.addOption(getOption(OptionConstants.bucket));  
  cLine.addOption(getOption(OptionConstants.fileLocation));  

  // Create, setup and deploy the CommandThread  
  GUIInteractiveCommand command = new GUIInteractiveCommand(cLine, console);  
  command.addComponentsToEnable(enableOnConnect);  
  command.addComponentsToDisable(disableOnConnect);  
  if (!getValue(OptionConstants.mountLocation).equals(""))  
   command.addComponentToEnable(mountButton);  

  // Piggy-back a Thread to start a StatReader if the call succeeds.  
  class PiggyBack extends Command  
   {  
    Configuration config = new Configuration("piggyBack");  
    OptionConstants fileLocation  = OptionConstants.fileLocation;  
    OptionConstants statsFilename = OptionConstants.statsFilename;  
    OptionConstants mountLocation = OptionConstants.mountLocation;  

    PiggyBack()  
     {  
      config.put(OptionConstants.fileLocation, getOption(fileLocation));  
      config.put(OptionConstants.statsFilename, getOption(statsFilename));  
     }  

  @Override  
  public void doPostRunWork()  
   {  
    if (retVal == 0)  
     {  
// TODO move this to the s3fronterSet or mounts or something.  Take advantage of PiggyBack's scope.  
      connected = true;  
      statReader = new StatReader(eventHandler, config);  
      if (getValue(mountLocation).equals(""))  
       {  
        OptionBox optBox = getOptionBox(mountLocation);  
        optBox.getOption().setRequired(true);  
        optBox.requestFocusInWindow();  
       }  

      // UGLY HACK... Send a 'ps aux' to grab the parent PID.  
      setNextLink(new PSCommand(getValue(fileLocation), null));  
      fireNextLink();  
     }  
   }  
 }  

PiggyBack piggyBack = new PiggyBack();  
piggyBack.setConsole(console);  
command.setNextLink(piggyBack);  
return new CommandThread[]{command};  
}  

Answer 1

It doesn't matter.

1) Develop a style that is your own. Whatever it is that you find easiest and most comfortable, do it. Try to be as consistent as you can, but don't become a slave to consistency. Shoot for about 90%.

2) When you're modifying another developer's code, or working on a group project, use the stylistic conventions that exist in the codebase or that have been laid out in the style guide. Don't complain about it. If you are in a position to define the style, present your preferences but be willing to compromise.

If you follow both of those you'll be all set. Think of it as speaking the same language in two different ways. For example: speaking differently around your friends than you do with your grandfather.