Copyright Folding

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.

Most source files have copyrights on them. When opening a file you have to scroll
past the copyright, and the import statements, before you get to the interesting part -
the class javadoc comment. Most IDEs now have a way to have the import section automatically
folded. But what about the copyright section? It's often quite large - in Apache
source code for example the copyright is 50 lines long - that's more than a full
editor page. Code folding to the rescue!

NetBeans has support for user-defined folds. In Creator, we use this to hide
the bean getters and setters, since that segment of code is never interesting
to a user, but nevertheless should be part of the source file and discoverable and
editable by expert users.

You can use this facility yourself to create arbitrary folds around code.
One obviously place to do this is around your copyright sections. These are ideally
suited because a copyright is a piece of static text which is replicated in each and every
source file. Just change your copyright template once, and from now on all new files
will have folded copyrights. In the Creator source base we have marker tokens in the
copyrights such that we can update the copyright sections in an automated yet safe way.

(Note: In NetBeans 4.2 you can set an option to have the first comment in the
document automatically folded. This will also achieve copyright folding if it's
the first comment in the document. Of course, you can apply folding to other logical
portions in your document too - there's nothing comment-specific about user folds.)

Here's how user-defined folds work: Simply add two Java line comments (//), one
to indicate the start of the fold, and one to indicate the end. The comment
itself has an XML-like syntax:

// <editor-fold defaultstate="collapsed" desc="Your Fold Comment">

You can leave out the defaultstate attribute if you don't want the
fold to default to a folded state when the file is opened. Obviously the
desc field is used to supply a description which is shown when
the section is folded. Note that the comment isn't truly in XML format in the
sense that you cannot reorder these attributes.

Let's see how this works in practice. Here's one of my source files, using
the short copyright version. Most other file licenses I've seen have a much
larger copyright than this, so the folding payoff is higher.

First I simply add the begin and end folding comments as described above around
the code I want folded.

Now, when I open the file (or collapse the file by clicking on the - in the margin),
the copyright takes up just a single line, and the fold description is displayed instead:

Finally, note that you don't have to expand a fold to see what's inside - simply
hover the mouse over the folding box and the contents are displayed as shown here: