Book review – Clean Code


Some time ago I read Clean Code, a very good book by Uncle Bob on how to write clean code, or should I say: how to polish written code until it becomes cleaner.

My first read through is something he calls at the beginning of the book a “feel good read” as I didn’t work hard and sweat, so I haven’t yet the full benefit of the book.

But I think with this first read I’ve gotten the general Idea and I have some quibbles about some parts of the book. I feel I should address them.

This is usual for me when I read his writings, some things I agree, a few I disagree and a couple I strongly disagree and once I very strongly disagree and then a I strongly agreed.

The one In this book I strongly disagree and made me start to write this post is about the exceptions, and then I let this post sitting for some time.

But I came across some people following the advice and I felt I should come back and publish this.

As he said in the beginning of Chapter 16, this is not in malice and I do not think myself better than him, my code is as flawed as the next guy as you can see from my contributions to the [Layout Parser] (

I have extracted from the book a lot of good advice which I shall incorporate in my own coding practices, there are some that are contrary to my believes and made me, at least, question the truth in them.

Yet there is always benefit in reviews and feedbacks.

Do not mislead

It is very well stated in the book that one should not mislead his reader and the code should do the least surprising thing and that functions should do one thing.

I happen to agree with that and I find the function renderPageWithSetupAndTeardowns in Chapter 3 given as example and refactored until clean to be still offending those principles.

If I were reading a code that makes a call to that function I would just assume that it decorates the page with setup and teardowns, on a debugging session searching for why the page is not being rendered with them it would be the last place I would look for the test if(isTestPage), I would expect this decision would already be made in order to call a function called renderPageWithSetupAndTeardowns.

So it surprises me by doing two things which is rendering the page and deciding if the render will be with or without setups and teardowns.


There are some criticism about javadocs should be written:

  • Should not express what function and parameter’s names already convey.
  • Should not contain mark-up.

But javadoc is not code and the audience for javadocs is not programmers maintaining the code, javadocs are for the API clients and thus it should not rely on the code.

With modern editors you can simply collapse the javadoc comments, if they are too bulky for your taste, and just ignore them.

So the content of javadoc should be as complete and useful as it could be without being constrained by rules intended by code readability. They are two different concerns.

Checked exceptions

Here is where I think the book is deadly wrong and it is even doing a disservice to the craft, he even declares the debate over, personally I think no one is ever capable of declaring a debate over.

Anyone that is regular to any forum can attest to that…

Let’s look at his arguments:

The price of checked exceptions is an Open/ Closed Principle violation. If you throw a checked exception from a method in your code and he catch is three levels above, you must declare that exception in the signature of each method between you and the catch. This means that a change at a low level of the software can force signature changes on many higher levels.

Note that if a given function throws an exception, and this exception will be meaningfully handled three levels above the open/closed principle is already compromised.

Regardless the fact it is declared or not, there is a distant class dealing with it. If it come to pass that the exception is changed the handler class will have to be changed too.

On top of that if an exception was allowed to merrily float up, that means it went up likely three abstraction layers and we have a high abstraction layer dealing with low abstraction guts.

Which brings us to the next argument against indiscriminate use of unchecked exceptions: they favour leakage of abstraction.

Through checked exceptions, java forces you deal with the possible problems that may arrive, letting the abstraction bubble to burst must be an active decision.

On the other hand, with unchecked exceptions you may not even be aware the abstraction is leaking until it happens and that may mean production time.

Which brings us to yet another argument against unchecked exceptions: they violate the principle of least surprise.

What a piece of code does is not merely a question of what the happy path does, the way the code fail is equally relevant. When I come across a signature which says:

File open(String path) throws FileNotFoundException;

It is telling straight away everything that can happen. I can mock the object and make the mock throw the exception and then I can write code to deal with it, and if I decide to let the exception go up I can wrap it up in a meaningful exception according to my abstraction, say: UnableToLocateCustomerException.

On the other hand if it is all unchecked and the client of my code has the interface:

Location locateCustomer(Customer customer);

He will have quite a surprise to see a FileNotFoundException to blow his nose, it is completely unexpected, as the Spanish inquisition, he does not care and should not care if my code uses files, data bases or smoke signal to store its data.

Declaring the throws clause in every method in the away the exception travels is not the dirty part of the code.

Letting it go up the abstraction and handle it where the exception is less meaningful and there is less chance of doing something useful with it, this is the dirt.

Making them unchecked merely hides the dirt under the rug and makes it harder to test and allow the dirt to grow mould until you find about because you are sick.


Today I worked a bit on the garden, that is not something I used to do much, but now we finished the move to Montreal and we’ve got a place with one so that our son can enjoy a bit of the Great Outdoors(TM), indoors.

And I was wondering how much gardening really resembles programming, the book by Steve Freeman and Nat Pryce: Growing Object-Oriented Software, Guided by Tests is spot on with it’s name.

At the beginning, nobody knows what they really want out of the garden, people kind of agree that they need a bunch of green stuff in it. So some beds are raised and seeds are sown, patches of grass are placed and some plants are pasted from other gardens.

But programming as gardening is not about just growing stuff. If you do, you end up with lots of weeds(hacks), dead branches and leafs and a bush of thorns that requires a good stretch of imagination to be called roses.

Unfortunately that is the state in which most software produced and my garden can be found, to have a garden you must do lots of trimming and cleaning(re-factoring) you have take out the dead branches and the sick plants you have to remove the hacks and cover the soil so that do not grow back.

At each trimming iteration the garden becomes less ugly until it may start becoming beautiful. If you stop trimming or take too long to trim it again it becomes a tangle again.

A good program is just like that, the best are very like bonsai, small, well trimmed and it’s growth directed according to its natural inclinations.

Life Long Learning for all of us

An Unschooled Future

I have moments in my life when I can literally feel my thinking expanding – I can almost hear my old thoughts being torn up and discarded and replaced by new thoughts or a new way of seeing.  I experienced this having lunch with Connor today.

We have just started an absolutely brilliant course, on Coursera, by a Professor from Tel-Aviv University on ‘The Emergence of the Modern Middle East‘.  We were watching this while we ate lunch this afternoon.

I have previously considered myself moderately well-informed on the history of the area, the way in which Western powers just divided the lands up into countries with no thought to the people living there, the completely artificial imposition and creation of the State of Israel supported by the U.S. to block the perceived threat to their interests in the Middle East from the Soviet Union etc.

I now realize…

View original post 790 more words

Feedback Loop

So I was reading this blog by Bob Marshall and at first I got angry, and then I realized I have being doing too much of angry, as I read I realized that not only he was not wrong, but also he was dead on right.

He did express exactly what I want.

I do not want the word back, I want what it meant to be, regardless of the name given. Going about making noise does not solve anything, if there is not a direction and a metaphor to work by.

So, really taking “agile” back must be done in “agile” way, lets do agile in anger(1) instead of doing it with anger, who says this is limited only to writing software?

Starting by feedback, what went right? What went wrong? How can we improve it?

And the first thing I think went wrong are the names, extreme programming scared people, most never went on to understand or learn anything related.

Agile is misleading and an attractive word for corporate drones in love with titles. It is too easily interpreted as fast, it also has an inherent aggressiveness, in the sense of hormone pumped up sport player “going for the kill” in a game, that appeal for those kinds of alpha male management types that love so much to be in control of everything.

My suggestion is to use Organic Development, organisms adapt and react to changes of context, organisms fail fast, organisms learn and improve through feed back loop, evolving and doing better for the context over the time.

I think Organic Development offer quite an extense source of metaphors to be used and to explain what we call agile.

(1) I just learned this expression, found it cool.

Everything else

So I am drunk, this is a post that fits in those posts on the everything else part of the blog, I advise you to stop reading here, as per I am drunk. I just came back from my meeting with my sister, she makes me feel happy and proud.

She is so much more than me and she has a very beautiful family, she has done an wonderful job at raising hers daughter and I hope I get to be half as competent as her in raising my son.

She and my brother-in-law loves beer and we went to an nice place: emporio do alto do pinheiros <- you see, my markdown powers are not diminished by alcohol, long live Aaron Swartz legacy on many things that matters.

The place in question sells beer from around the world. Long live British beer! You guys are invaders and meddlers but you are redeemed by your beer. Americans not so much, you are even more meddlesome so you must work harder on your beer, you have much to improve, you have to acquire elven standards on beer to compensate for the amount you meddle in peoples internet and general affairs.

Bottom line, as much as someone in my condition can reach a bottom line without being the bottle one. Aliteration…

British beer is the best, closely followed by Belgium, for a nice surprise Norwegian was very good too, American not so much, don't do drugs, do not drink Brazilian's we are not as half as meddlers as anyone and yet our beer needs improving.

Also I am happy, very happy! Me, my wife and my kiddo are moving in to Montreal, which seems to be a fine place to raise him, I am on my last days on the drone factory that has become my job and the future seem brighter and sunnier although in a snowier place.

I also have to thank Bob Marshall for his post on rip agile. It was eye opener, I realised I don't want agile back, it is a bad brand, seriously people, who came out with this name? It is bad, it does not capture more than buzzword, it was bound to become something corporate zombies label horny would abuse.

I want to be treated as a human being, I want an Organic, Mindful, Soulful software development. Hint: Corny labels do not get abused by corporate drones.

I want the essence back, the dead empty shell the drones can have and feed on it.

Tomorrow I will regret this post, but the me from today vow not to let the me from tomorrow to take this down.

Peace out people, be happy.

The Fear of Agile Transformation

Excellent article, fear of change and lack of willingness to try out new things and risking failure is the single greatest enemy of agile adoption and success in most endeavours.

All Things Agile

“The snake which cannot shed its’ skin has to die.  As well as the minds which are prevented from changing their opinions; they cease to be mind.”  Friedrich Nietzsche

Recently, I was attending a Deep-Dive study group that was hosted by Lyssa Crispin and Michael Spayd of the Agile Coaching Institute.  During our discussions, I began to think about all of the agile transformation efforts I had participated on and what, in my opinion, seemed to be one of the deterrents to a successful agile transformation.

What I determined was that a good percentage of people that resisted the change to agile came from a very strong command-and-control background—individuals that were managers, at all levels, who were accustomed to being in charge and commanding people to do things, sometimes down to the task level.  Not all of these people were project managers, some were senior technical leads who had reached…

View original post 925 more words

The noble pursuit of ignorance

We’ve got our brains hooked up in cyberware(sort of), we have more data at our fingertips than any of our ancestors ever dreamed or dreamt of.

The big word of the moment is Bigdata, or how to search all this information. Maiden’s Prisoner starts playing in the background.

While through machine learning and pattern matching we make mechanical constructs try to emulate the most sophisticated pattern matcher of all, we deface and mechanize human beings turning them into machines unable to make inquires and search for answers.

Just numbers, prisoners to the mentality of the colonial and industrial age. Repeating the same “right answers”, learning nothing useful and being used like poor man’s hard driver in an gigantic cluster of replicated data, pieces to a dead machine. Unable to claim our rightful ignorance.

Not numbers, free-humans, let’s have minds of our own. Let’s start to convert all this data in wisdom and search for our high quality ignorance.

Wired to pair

The more I think of the practices the more I like pair programming, it is the one practice with a plethora of benefits from code review without attrition to source of social interaction, enforcement of good practices and code style, diffusion of information among team members, activation of learning part of the brain associated with social interaction…

I just came across an article that I again see relation to pair programming, we are wired to handle better stressful situations by sharing the burden as it is shown in this article.

I think it was twitted but for the life of me I can’t find the original reference, this was sitting on my bazillion of tabs to be read for some time.

Fun and Agile


I figure that if we are to take agile back we should not let pass remarks that destroy the spirit of agile and we must reinforce what agile stands for.

So this is a kind of extended off-topic reply to a discussion in the linked in group about agile where I felt that a core tenet of agile was offended.

This is of course, my opinions on the subject, both on how to handle take agile back as on the subject at hand.

The issue

In the discussion about how to teach agile there were some people suggesting the use of games, in response it was stated by someone that:

  1. Agile is not fun;

  2. Agile is not a escape for the lazy or ones that don’t want to work hard to learn and upgrade their skills;

  3. Agile causes burnout;

  4. No pain, no gain.

The affirmation (2), I think is the worst off all, because it shows that you mistrust people by default. It is carrots and sticks all over it, it’s a gross misunderstanding on human motivation and that humans strive for mastery and achievement and it is precisely this distrustful culture that puts people on the defensive and utterly creates an environment of underachievement motivated by fear and conflict.

Human centred

A central characteristics of Agile, at least which I see as being core to Agile, is being Human centred and organic, contrary to more traditional methodologies that try to force human beings into forms, agile tries to understand humans and build around them in order to maximise the positive qualities and to smooth out defects.

Instead of destroying human beings by trying to make them into machine pieces and fit an arbitrary median norm, ending up with barely functional pieces, performing at the average minimum, Agile builds upon people and maximises contribution of each participant in the process, leveraging each individual’s qualities and protecting the whole from defects.

In order to archive that goal it is necessary to understand the human being which can only be done by understanding of human physiology, psychology and sociology. As with agile we are always in the feedback loop learning and improving, a good amount of empathy.

No carrots please

The first thing to understand is that we are not motivated by rewards.

It is an established knowledge that intrinsic motivation is much better than extrinsic motivation, there are experiments that show that if a person likes something and is paid to do it, she will like it less afterwards, for we associate the act of doing with the reward being the cause and not an intrinsic motive and the subject becomes less interesting.

Fear is the path to the dark side

When we are in fear or stressed, the reptilian brain takes over and shuts down the creative problem solving part of the brain, we enter a fight or run mode where route response and pre-programmed behaviour takes place.

Software development is intellectual work

This is an important point to realise, the least important part of programming is the actual writing of code, for that we have IDEs, where development bogs down is the design part when people are at lost on how to solve a problem, how to uncover a bug, or even worse when they are producing badly designed code that will “work” but later come back and haunt the team.

Intellectual work is very different from mechanical work for you don’t just drop it at the end of the day and restart the following day, where measurement of a task progress is merely the amount of stuff produced.

In intellectual work the task is ongoing 24 hours a day, our brain does not simply switch off from the task, it keeps processing unconsciously the problems and the creative process goes on and on.

The reason people have so many great ideas in the bath, when we bathe we are relaxed, running hot water is specially good at releasing hormones that causes relaxation, this engages the creative part of the brain, the pre-frontal cortex, ideas get finished and flow from the unconscious mind.

To maximise intellectual productivity one must keep the pre-frontal cortex engaged, this means being relaxed and avoiding extended period of stress.

Work around limitations

While command and control industrial age philosophies try to enforce policies and force people to follow an huge amount rules, Agile tries to remove the burden and set tools and mechanisms which would be the least intrusive, stressful or demanding, to let people do what they really excel at which is to think, have ideas, solve problems.

For example instead of using late code review which causes people to feel uncomfortable and judged, Agile uses pair programming which incorporates hot code review among other things. Instead of e-mail, planing tools, reports… A simple white board with histories.

The more you make people feel safe, comfortable, empowered, reduce bureaucracy noise, the more they will focus on actually working and produce stuff. If the process takes unto itself the role of compensating for the weakness, people can focus theirs energy on what actually matters.

To tire is an human weakness and thus it must be addressed by the methodology, if it is allowing people to burnout it is being done wrong. In fact there is a maxim for that: Work refreshed.

We advance when we rest

Affirmation (4) no pain no gain, is a often repeated catch phrase, when we workout we cause lesion to tissue but when we rest, during the deep sleep, tissue is repaired and the body “learns” by forming better structures, the same goes for mental learning, during light sleep our brain organise information and commit to long term memory.

We know today when we exercise up until just before the pain, recovery is much faster and gain over time is greater than going past to pain, besides, exercising until pain there is formation of micro scars, which over time cripple the tissue. The same goes for mental health, if you rest before stress you recover faster, learn more and prevent mental injury.

The correct phrase would be: No rest, no gain, pain and eventually death.

We evolved to play

Play is a fundamental need for human beings. We evolved to play, it is the natural way for our species and many others to learn, when we play we are at the proper mental state for learning. There is a beautiful TED Talk by Steve Keil on the subject in which he does an excellent job at advocating for play and fun to boost work.

By promoting play and games you promote the development of skills without suffering, boredom and stress.

Fun is serious business

How do you maximise brain work in an unobtrusive way? Fun of course. If you reconcile fun with work you will have more brain power and less burnout. Actually, in order to be Agile, there must be fun.