Clean Code Tricks — Intention Revealing Messages

Intro

It’s easy to dismiss “clean code” as a myth or “only for the
perfectionist”, and who am I to say that is wrong? Well, I can’t say it, what I
will say is that I have found clean code to be real, to be immediately valuable
and to be an easy habit to get into. I have found clean code reduces the
cognitive load when you are trying to unravel the mysteries in code.

I’ve picked up some clean code techniques from www.cleancoders.com (Uncle Bob), Code
Complete 2 (Steve McConnell), and Smalltalk
Best Practice Patterns (Kent Beck). I’m also always on the lookout for
more.

In this indefinite series of posts, I’ll share my favourite
techniques and the reasons why I love them.

As always, I continue to learn and respect other people’s
opinions. Nothing is part of my religion — just the way I currently perceive as
the best approach to writing code. If I gain new insights from others or from
my own adventures, I’ll be sure to present them.

Intention Revealing Messages

Intention revealing messages are at the heart of clean code
- they are methods which contain only small pieces of code. Their goal — to
explain what the small piece of code, sometimes just a single line, means.

My favourite place for intention revealing messages is the
conditional in an “if statement”.

Benefit

If a method name tells me what the condition means:

·
I don’t have to work it out myself

o
Saves me time

o
saves me hassle

o
saves my company money

o
reduces potential for misinterpretation

o
highlights a bug (where the name doesn’t match the implementation)

Cost

A method signature and a pair of curly braces — sounds like
a deal.

An Example

if (row
> 0)

Rows[row][column].Above = Rows[row — 1][column];

This is one if block in a block of 5 and I’m trying to find a
bug which could live in any of them.

First of all, I have to work out what the author intended.
What does row > 0 mean? After reading associated code for a few minutes,
it means “not the top row”.

I then have to work out what the code block means — “set the
cell above reference on this cell, using the cell above this one in the row
above” — which takes more time.

Now imagine that this block of code is only a smart part of
a larger area of code which might have the bug — I’ve got to decode lots of implementations
to work out the high-level algorithm — and then check the implementations match
what I “think” the author intended.

A solution

If I refactor small implementations into methods (intention
revealing messages), for each block, no-one has to work out the intentions –
only that the implementations match the intentions, or the intentions are wrong:

if
(!IsTopRow(row))

SetCellAbove(row, column);

Now I can walk through the code and read the algorithm in
English language. If the algorithm should work theoretically, then I can check
intentions (method names) against implementations (method bodies) — the bugs
will jump out at me. If the algorithm is flawed, then I don’t need to need to
dip into any implementation.



Note: I’ve inverted the expression to keep the query positive (a common standard)

Source

Intention revealing methods are presented in Smalltalk
Best Practice Patterns Using them in this way is recommended by Rob Martin
(Uncle Bob) on www.cleancoders.com
(episode 3).