A Technique on Comments: The Separation Banner

In a lot of commenting best practice articles much ballyhoo is made of commenting in the small (single lines or methods) or at the class level (headers, footers, etc), but it seems hard to find anything in between (e.g. what is a good way to separate major parts of a single class).  This article will explain a technique I've seen used, but haven't seen named before or expounded upon: The Separation Banner.

Quite simply, a separation banner is used when you need to demark major blocks of a class or other source-file (assuming you aren't using Java) to aid in visual navigation and in keeping the class in order.  The pattern I've seen the most is a line of slashes (i.e. enough to fill up to the 80 column), two slashes + text, and another line of slashes.  E.g.

  //////////////////////////////////////////////////////////////////////////////
  // IFoo Implementation
  //////////////////////////////////////////////////////////////////////////////

Other examples for the text inside can be things like "Accessors" "Static Methods" or "Inner Classes".

Humorous Image brought to you by
Digital Storytelling and The Simpsons

In general, I have found the separation banner to be quite useful, and created an Eclipse code completion entry for it so I can avoid adding all of those slashes every time.  As always, you can have too much of a good thing so having one banner for every five methods or more (roughly) has worked for me.

So, next time you frequently get lost in the inner muckings of a class, consider adding some additional structure with a separation banner.