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.

Documenting Facelet Components

Right now I've been trying to figure out how to properly document Facelet includes, Spring Web Flow directories and Facelet components.  It seems that for Facelet components you're to use the JSF Tag Library Descriptors (TLDs).  I've been having a rough time finding how to do TLDs on the web, and could only find the (somewhat dry) entries for the Java EE 5 Tutorial and Java EE 6 Tutorial.

I read all of these docs a few months ago, before "getting my hands dirty" by actually using these technologies on a project.  It looks like time for a re-read.

@see autogeneration

Greetings, this post is for programmers.

For everyone left, I thought of making an IDE plugin that would generate Javadoc for fields automatically. Namely, it would do a search for usages and insert a @see Javadoc automatically. This would help for fields in large classes. Maybe if it was used in more than 3 or 5 places it would just have a total count.
IE:
@see Method2
@see Method3
or
Used in 21 places.