PL/SQL, JSP, Java, and Javascript 'Beautifiers' (Reformatters)
Charles Roth 21 July 2003
Last revised 7 February 2007

I. Introduction
In my first major foray into the source code for CAPS, I had the dubious pleasure of modifying largely unindented and unformatted PL/SQL and Javascript.  As I am a big fan (one might say evangelist) of readable code, this situation was untenable (see thedance.net/~roth/writing.html).

But what to do?  Manually reformatting the code was out of the question.  But plenty of tools exist that will automatically reformat code; the problem reduces to one of basic research.  Google to the rescue!

II. PL/SQL
There's one clear "winner" for formatting PL/SQL: Formatter Plus (aka F+) from Quest.  (Thanks to Erika for the initial lead.)  The good news is that F+ is compatible with (can be launched from) both SQL Navigator and Toad.  The bad news is that F+ is commercial and proprietary: a single license is $200.  The good news (see a pattern?) is that 30-day trial versions are downloadable from the link above.  The even better news is that a single copy, put on our network, might suffice for our needs.

F+ has a large array of formatting options, which are pretty logically arranged in the collapsible menu shown on the right.  My favorite options are:

The installation was trivial; download the 30-day trial, and run the installer.

The operation was also pretty easy.  In SQL Navigator, click on "Tools", "Formatter Tools", "Launch Formatter Plus".  Once in F+ (it gets its own independent window), open your PL/SQL file and click on "Text Editor", then "Format Text" (or just press F2). 

The 30-day trial version apparently does not allow you to save the results (it hung when I tried).  But it's easy enough to cut-and-paste the formatted text window contents into Notepad, and go from there.  (I wouldn't want to do that every day, but for just reformatting old code, it's well worth the little bit of effort.)

Note:  This did cause me one nuisance when I went to use the reformatted code in an implementation checklist: the MKS "diff" result was huge and useless.  The solution was to reformat the "version checked-out" code, and do a diff against that with my new code. 

(Nov 2004 -- I just received word of a new entry, from Semantic Designs.

III. Javascript
Not surprisingly, there are a wide variety of Javascript formatters available -- there's a (probably) larger and (definitely) more varied audience of Javascript developers, compared to PL/SQL.

I found two that seemed "best of breed", one commercial, one free.  The winners were Trita (commercial) and Javascript Code Improver (free) -- although you may also want to look at the Semantic Designs family of code formatters, and the free Arachnophilia, which has many HTML-improver capabilities as well.

Trita has some excellent ease-of-use aspects.  It has three different ways of specifying your formatting preferences, the easiest of which is a code sample!  You simply modify their standard code sample to look the way you like Javascript to look, and it uses that as a template.  Also, to reformat a file under Windows, just right-click on it in Windows Explorer.

Trita costs all of $35, and offers a free download, with pretty much the same limitations as F+ (cut-and-paste from formatting window, etc.)

The Javascript Code Improver is extremely simple, and has just a very few options (indent size, open brace on same vs. next line).  It's trivial to use, and is, after all, free.

IV. Java
Java also has a clear winner: Jalopy.  It's both very powerful and Open-Source, and thus free.  It even has a page that lists related tools, if you want to pursue other options.

I found Jalopy somewhat tricky to install and configure for use from the shell (command line).  It does have a ton of "plug-ins", i.e. ways to plug Jalopy in to existing Java IDE's (integrated development environments), which is all to the good.

Updated February 2007: Of course, these days if you are coding in Java, you should be using Eclipse or some other IDE that has a code-formatter built-in.

V. JSP
Added February 2007: I looked long and hard for a good JSP formatter, as there is one hell of a lot of ugly JSP code out there.  So far my best experience is with NXformat, nee' JSPformat.  It's a commercial product, but US $99 for a three-user license is worth it.

This is a bad news / good news / bad news / good news... story.  I found a lot of bugs in the early versions.  But they fixed them very quickly.  But I don't like some of the formatting options (e.g. no tabs).  But I wrote some simple pre-and-post processors to take care of that.  But... well, you get the idea.

(Supposedly NXFormat will plug-in to Eclipse, although I haven't made that work just yet.)

If you are aware of other good JSP formatters, please let me know.

VI. Notes on Coding Style
When you think about code format, think beyond just indentation.  I have been working with, and in some cases rewriting, code formatters for over 20 years, starting with FLECS, a structured Fortran preprocessor.  In that time I have synthesized my experience into a few simple rules:

  1. Use automatic formatters.  Adding more code to existing unindented code, without reformatting it, verges on unethical and unprofessional behaviour.  There's no excuse for making a mess worse.

  2. Always indent blocks by 3 spaces.  Never use tabs.  (Less than 3 is to small to see; more than 3 takes up too much horizontal space.  Keep your lines to less than 100 characters, ideally less than 80.)

  3. Put block openers (e.g. "{", "THEN", etc.) on the same line as the statement that started the block (e.g. "IF").

    Block openers are purely "syntactic sugar".  They add absolutely no semantic value to the code.  As you read the code, your eye should follow the indentation, not the tiny "}"s or "END"s.  The notion of putting the block openers on the next line simply wastes vertical space -- which means you can see (and thus understand) less code.

  4. Don't use ALL UPPER CASE unless there's a particular naming convention -- e.g. putting all SQL keywords in upper case.  Your eye is well trained to see upper case letters as "stops" -- indicating the beginning of one sentence (and thus the end of the previous.)  Using all upper case is forcing your eye to stutter.

  5. Use horizontal whitespace and parentheses to make small chunks of code easier to read.  Compare: 
       for (i=0, j=15; i < 37 && j <52; ++i, ++j)

   for (i=0, j=15;    (i < 37) && (j < 52);    ++i, ++j)
    Which is easier to read?  Why?

  6. Use horizontal whitespace to align vertical chunks of code.  When code must wrap across multiple lines, use whitespace to made the associations between the lines more obvious.  This is useful in declarations of many variables, in long parameters lists to functional calls... even in groups of related assignments, e.g. 
       x  = (y -c ) * (y -b ) + a;
   x1 = (y1-c1) * (y1-b1) + a1;

    You may think it's a lot of work -- but it's less work in the end than reading code character by character.  It also helps if you find and consistently use, a powerful editor.  It doesn't matter what it is, but find one that does the things you most need for you.  At the very least it should do brace or block open/close matching for you, or verify the matches.  Otherwise you might as well be punching 80 column cards!

  7. Simplify code that generates code.  For example, in PL/SQL, replace: 
       htp.p ('function do_something (x) {');
   htp.p ('   var y = 2 * x;');
    with 
       htp.p ('
      function do_something (x)
         var y = 2 * x;
   ')
    (Thanks to Srini B for pointing this one out.)

  8. Develop and use a standard header comment.  In particular, that header must describe the purpose of the code, and the context in which it is used.  (Imagine reading vehicle driving instructions without knowing if you were in a Lamborghini, a VW bug, or a shopping cart.)  The purpose description should be no less than three lines! 

    Or see my extended rant on the subject at thedance.net/~roth/writing.html.