Style/Formatting: Vol 1

Style or formatting is the most ignored practice in all of programming - well, arguably. To me, formatting represents the single most important part of the coding. Formatting has the potential to do the following to the code:

• enhance the understandability of the code
• make the code easier to read
• reduce the amount of time a developer spends deciphering what the author intended
• encourage good programming practices
• speed up the development cycle
• illuminate stinky code, cheats, shortcuts, hacks, you name it
• reduce the learning curve for new developers
• lend a consistent pattern to all methods
• uncover hidden code complexity

One of the problems with style is choosing one that everyone will agree on as the best. Another problem is getting everyone to adopt the style that is chosen. Finally, getting everyone to consistently repeat the style and not do it only some of the time.

With smalltalk, I’ve seen many different styles, usually an amalgamation of several different authors with different styles that achieve different purposes. I’ve only found one style that encompasses a holistic approach to software design and patterns; only one that achieves all of the bullets above and a few benefits I’ve forgotten. That is the one proposed by Kent Beck in his book Smalltalk Best Practice Patterns in Chapter 7. The styles he presents are so common sense, I can hardly believe that not one of the smalltalk distributions have adopted it. With so many smart people, why can they not see the genius in this style guide.

I just don’t understand why style is ignored to the extent that it is. Code is more important than good code unfortunately and I guess that is the main reason why. I can understand each shop wanting to employ a style of their choice, but shouldn’t the baseline formatting be the best that is available. I welcome a debate on which style guide is best. Some will win in small scenarios but nothing that I have seen or read about touches the brilliant guide that Kent Beck put together. I may opt to adjust a few things in his guide, but nothing very big, and nothing I simply “have to have”.

So, what makes a good style guide anyway? I believe that it begins with the phrase, “no exceptions”. In other words, very very consistent. Another measurement is in regard to readability. If the code formatting itself can relate to me the flow of the code, I can read it much better.

Consistent is a bit ambiguous when discussing code styling because one must consider indents, contexts, and other punctuation and syntax. The most consistent will cause all the rules in the style guide to always be true.

Here’s a little example, in Smalltalk, of course:

^1 = 1 ifTrue: [1] ifFalse: [0]

Now, after applying Kent Beck’s style guide:

^1 = 1
   ifTrue: [1]
   ifFalse: [0]

While the first example is more concise, and I know a bunch of programmers love concise code, the rule is that whenever the receiver is sent a multi-named method, it’s components drop down to the next line.

The readability of the code may not seem much different in this example, but trust me, legacy systems can include some herculean methods and following them is next to impossible without Kent’s formatting. And, that is the point. Using this style guide works for all cases, bar none.

Here’s a slightly more complex example:

[one=1] whileFalse: [one:=self getOneForDate: Date today withId: 3.
one=9 ifTrue: [ self displayNine] ]

I agree, the above method isn’t terribly good, but its only purpose is to illustrate how styling can improve readability. Here it is again, formatted according to Kent’s style guide:

[one = 1] whileFalse:
    [one := self
        getOneForDate: Date today
        withId: 3.
    one = 9 ifTrue: [self displayNine]]

I will talk more about each of the style rules in more detail in subsequent posts. I only wanted to introduce the topic here to get me started.

The second example is far easier to follow and gives us little to decipher. Instead, the code just speaks to us because we expect it in a certain form and it is always in that form. There’s little guessing about how this little bit of code operates, horrible as it is.
Let me add an ifFalse: to that last part and see how it changes:

[one = 1] whileFalse:
    [one := self
        getOneForDate: Date today
        withId: 3.
    one = 9
        ifTrue: [self displayNine]
        ifFalse: [self displayEight]]

In essence, whenever a chunk of code takes up more than one line, it begins on the next line. Multi-named methods constitute more than one line.

So, that’s a start. Styling can reshape the way we view solving problems, it can reshape our thinking so that the language doesn’t entirely exist. Instead, Smalltalk becomes a kind of blur in the background as we design elegant and patterned applications and spend most of our time testing and refactoring.