The "Hedge" -formatting convention

OR: Why it's better to put the separator in the beginning of the line.

Assume you have a data-structure such as the list of 'months' shown below. When you have such a structure, you often want to add new items to it. That is easiest to do by copying some existing item and then modifying it to suit your purpose. At the same time you hope this will automatically give you another syntactically correct structure - so you don't need to stress your brain much about whether syntax is correct or not, or type much to adjust it. The less you type, the fewer the errors you can make.

When you do that you also typically want to add the new items to the END of the structure. Why? Because that tells you most naturally the order in which the items were added. As an example think of writing down the months of the year as a list. You would most naturally add later months after the earlier ones:

var months = 
[ January,
  February,
  March
]; 

Looks pretty tidy, right? You have three months already written in correct JavaScript syntax. But now how do you add April to the list?

You can not simply copy one of the existing lines and put it into the end of the list. Or you CAN, but you then come up with incorrect syntax:

var months = 
[ January,
  February,
  March
  February,
]; 

So above is bad. Not too bad. But there is a better way to format code like above. I call it the Hedge -formatting convention:

var months = 
[ January
 , February
 , March
 ];

Notice above that because we read code from left to right your eyes will immediately pick the vertical 'hedge' that now gives a visual indication that all content to the right of it is part of the same structure. It is easy to see where this structure starts and where it ends,  by following this vertical 'hedge' downwards.

The opening and closing brackets are now PART of that same edge because they can be aligned with the separator character. It becomes easy to find the closing bracket of any opening bracket.

Am I missing some commas perhaps? That is easy to find out by following the "hedge".  Such a hedge needs to be on the left side if the opening and closing brackets are to be part of it.  And because we read (most programming languages) from left to right, your eyes will pick up the commas faster the more left they are.

With recursive structures the benefits of the hedge -convention are even greater, because it is easy to follow it consistently, and thus make the structure of your data visible and easy to verify syntactically.  In the below structure it is easy to add new elements to the structure by copying any existing element AFTER the first, adding the copy to the end of the list, and modifying the copy. Note that most lists contain at least two elements, else there would be little need to have a list.

It is easy in the sense that you will most of the time have a syntactically correct structure and you know it.

    var monthsAndWeeks =
    { January:
            [ week1
            , week2
            , week3
            , week4
            ]
    , February:
            [ week5
            , week6
            ]
    , December:
            [ week52
            ]
    };

So why is this so?  Can 'left' really be better than 'right'?  Why is left better than right? The answer is: Because we read and write from left to right. That convention has implications to the best way for formatting code.

It's important to see where a new component of a data-structure starts.  In the above example that is easy to see because the separator is at the beginning of the line. So reading from left to right we only need to read one character of each line, to know where each component starts.

© 2013 Panu Viljamaa