A New "Clean Code" Mantra
I'm a huge fan of Robert C. Martin's Clean Code handbook. While most of the recommendations are of the head-nodding "of course, been doing that for ages" ilk, a few of the solutions offered have been genuinely outstanding for improving the readability of the code I produce.
Here's just one example. Uncle Bob is all about the Short Method - and I'm totally with him on that one. Short methods neatly sidestep so many of the readability issues we often find when scanning code - be it someone else's or our own. It's pretty hard to get into a major stylistic battle with a "only ever one return statement" purist when the entire method is 5 lines long. But I digress. The issue I'd always had with Short Methods was where to put all of them. Say you have a class with 3 public methods, and 5 private methods that actually do the work. Do you structure your source file like this (classic C++ access-level ordering):
public methodA() public methodB() public methodC() private methodD() private methodE() private methodF() private methodG() private methodH()
Or do you put called methods immediately after their caller?
public methodA() private methodD() private methodE() public methodB() private methodF() public methodC() private methodG() private methodH()
But how should you arrange things when (private) methodF() is called by all three public methods, and methodD(), a private one?
My classes were a bit all-over-the-shop in this respect. I'd never really hit on a strategy that kept that uppy-downy scrolling through source files to a minimum. I'd get especially annoyed during debugging sessions in Eclipse - with all of the extra views running, it felt like I was looking at the code through a mail slot, and my mouse's scrollwheel was going to wear out.
Uncle Bob's solution is simple but effective; just arrange the methods like a newspaper article - more detail emerges as you work down. Top-level methods that orchestrate others live at the top, with more nitty-gritty provided as you scroll down the file. When you've got well-named methods that are written with the "principle of least surprise" at front-of-mind, you find most of what you need is within half a screen of scrolling of your current point of interest.
It was while I was refactoring a unit test with Uncle Bob's wisdom fresh in my mind that I realised I could combine three of his top tips into one new maxim. Take the recommendation that your methods should be short, combine with Single Responsibility Principle that a method should do one thing only, and add the fact that in today's age of modern languages and widescreen monitors, a method should have a long and meaningful name, and you get ...
Methods Should Be Wider Than They Are Long
Implicit in that commandment is that the method signature itself should be the longest line. Think about what you get if you honour this:
- If any line of your method is longer than its signature, you've definitely got too much indentation going on (and therefore need to refactor out whatever is causing that)
- As a counterpoint, if your method starts getting long, it's obviously doing more than the name suggests - and again it's off to Refactorville, population: You.