When a coder sits down to start banging out code
The first thing to start crowding his cognitive load
Is whether his program will do what it should
Correctness, he says, is what makes my code good
It’s the function that captures the coder’s attention
Behaviors and inputs and outputs are mentioned
As if the one good that a coder can bring
Is to spin the right wheels on some Turing machine
And compiling and linking and running are great
(We need to do these to put food on our plate!)
But the shocker that might leave you scratching your head
Is that actual code is less written than read
We spend more of our time in maintaining our stuff
Than we ever spend writing the simplest of cruft
Which means that unless you’ve got something the matter
You’ll try to learn just a few code style patterns
So coders and countrymen, lend me your ears
As I teach you some lessons won hard through the years
From that Beckian book about implementation
And patterns that derail code suckification
A classical problem is how to name things
(Oh, the anger and fights and dissension this brings!)
Like off-by-one-errors and cache expiration
A permanent answer’s beyond expectation
But a class should be named to describe its intent
Not its implementation, though that’s how were bent
A superclass name should be pithy and short
And the subclass’s name a more detailed retort
When you look at the name of a class you should find
The idea that hatched in the first coder’s mind
And just what is the thing this class wanted to do?
And what should you be thinking when first you call “new?”
When you can’t find a name for a class, it’s a sign
That the metaphor’s actually escaping your mind
A good metaphor helps more than comments or training
To inform other coders just what you are saying
The next thing we’ll consider together is state
(Which wouldn’t be bad if it wouldn’t mutate)
The functional people may think that they profit
But objects we code will change state; we can’t stop it
It’s not just concurrency where it can bite us
Although many suffer from thread-lock-wait-itis
The way that we organize pieces of state
Can make all the difference between good and great
Group similar state close together and see
Just what happens in time to your code quality
If you think of the reason your data is altered
Your sense of the meaning will be less assaulted
The things that are changing together should be
Very close to each other, viewed all on one screen
The data whose purpose is common? Same thing.
If they all work together, keep’em all in one scene
Remember the scopes an imperative language
Gives to you to gather together your baggage
The method, the instance, the class scope are able
To keep you from having too much on the table
The changing of state is a serious problem
And I think that we’re starting to locate the bottom
But as long as assignment is part of our ken
We’ve got try hard to keep data reigned in
See, the coder who’s reading this pile of junk
Is bounded in what he can think of at once
Don’t make him scroll all up and down every file
To find and recall every identifier
Now the methods we write can get out of control
When we make the one reading them scroll, scroll, scroll, scroll
A method that’s long and meandering is bad
But a method that’s short and composed makes us glad
To compose a good method, just think of the scope
Of the things that it does, and with that you can hope
To keep all of its actions around the same level
Or else its abstractions will leave you disheveled
A method composed by a coder who tries
Will read like a story with just one plot line
Each part of the story it tells is the same
As the rest of the method, with all the same aim
To understand just what composing’s about
Imagine a story of when you went out
And started the night by first changing your clothes
Then switching to tell me the distance you drove
Then up and describing the way you shift gears
And a long, pointless tale about your rear-view mirror
Then changing your story to cover the dinner
And how it was cooked and how long the sauce simmered
Then skipping ahead to the movie you saw
But not telling me even one detail at all
Now what would you think of this crazy approach?
My mental disturbance would be hard to broach!
It’s the very same thing when we factor a method
Each one should stay small with its purpose embedded
In a series of readable sub-method calls
And inside those methods go all their details
When people are learning, they sometimes prefer
First to know all the details and from them infer
All the concepts producing the detailed design
Either concept or detail can govern the mind
When composing your methods, keep this fact in mind
And please think of the coder who’s struggling to find
The whole shape of the picture zoomed all the way out
Or the flipping of bits when that’s what it’s about
I think if you’ve listened a little to me
You might start to catch what I want you to see
It’s good when we write code that passes its tests
But mere functionality isn’t our best
It’s the human who sits down to work with our code
Our ideas we want to this one to be showed
So remember this saying, to the best that you’re able
The reason you write code is to love your neighbor