Some thoughts on my favourite quotes of “The Clean Coder”

Last week I finished Robert C.Martin’s The Clean Coder: A Code of Conduct for Professional Programmers. It had been on my shelf for a year and a half, and last year I even started it and got halfway through it, but ended up forgetting it for some time. Until last month, when I decided to start it again, but this time, going cover to cover.

Chances are that you’ve come across it before, at least once. If you haven’t, then I’m happy you’re reading this post now. If you have, but it didn’t arouse an interest in you, then let this post serve as a reminder to you, software developer, that it is probably one of the few must-read books that you need to read. You might not agree 100% with everything that is said in the book, although you’ll probably agree with a big chunk of it, and if you’re like me, you’ll realise about things that you never thought of before, and you’ll find some other aspects of your job where you can still improve. One way or the other, I can’t recommend it enough.

With most books (technical ones, at least), I like to do a quick recap of the things that I liked most, or that caught my eye for some reason. I won’t do a review of this book, but I wanted to list here some of the quotes that I found more interesting. Not because they looked very poetic but because of the principles and attitudes they show towards the software development profession. So, let’s get straight into it.

Excerpt from the preface. On political pressure and experts’ advice:

Despite all the protest and memos, and urgings of the engineers, the managers believed they knew better. They thought the engineers were overreacting. They didn’t trust the engineers’ data or their conclusions. They launched because they were under immense financial and political pressure. They hoped everything would be just fine.

Fortunately enough, I haven’t been in this situation. Unfortunately, though, I’ve been quite close. The end result for the client was mostly some technical debt that had to be fixed and paid for later on, and it was certainly not the most desirable outcome. In the context of that quote, the implications of disregarding the voice of the experts were much more severe, which makes the whole chapter a great way of starting the book by highlighting that, even if software (no matter at what scale), our work matters, and it will always have implications.

PROFESSIONALISM

One whole chapter is dedicated to the concept of professionalism (the book is not called a code of conduct for nothing). It’s quite likely you can identify yourself with one or more of the next few quotes. Perhaps in a positive, negative, or even a neutral way.

On professionalism:

It’s a lot easier to be a nonprofessional. Nonprofessionals don’t have to take responsibility for the job they do – they leave that to their employers. If a nonprofessional makes an error, the employer cleans up the mess. But when a professional makes a mistake, he cleans up the mess.

Not much can be said about this one. It’s ok to make a mistake, and to mess something up. We’ve all done it. We’re not perfect. But it’s not ok to try and hide it or avoid facing the problems that come out of that. This is a bit of a cliche, yes, but it’s still important to keep in mind. It’s easy, as a developer, to be surrounded by smart people and think that it’s all cool, that they can fix it. Whether they can or not is one thing. Your responsibility is to clean up your mess.

On QA and testing:

Some folks use QA as the bug catchers. They send them code that they haven’t thoroughly checked. They depend on QA to find the bugs and report them back to the developers.

Never mind that this is a desperately expensive behavior that damages the company and the software. Never mind that this behavior ruins schedules and undermines the confidence of the enterprise in the development team. Never mind that this behavior is just plain lazy and irresponsible. Releasing code to QA that you don’t know works is unprofessional. It violates the do no harm rule.

Unfortunately, this is more common than one would think. I’ve heard dozens of times that “Developers are not good at testing their own work”. From time to time, I still see that idea floating around, and it still annoys me quite a bit. That’s not true. That’s simply not caring about the work one is producing.

Of course, you can be a good developer, care about your work, and from time to time you’ll produce bugs or minor mistakes that will be spotted in QA or during code reviews. That’s perfectly fine. But that’s one thing, and the other, completely different one is to perpetuate the harmful idea that producing code and not being thorough about testing it before passing it over to QA, is perfectly acceptable because, you know… developers gonna be developers. No. That’s just wrong, and that will give some people the excuse they need to not care about what they do.

On work ethic:

Your career is your responsibility. It is not your employer’s responsibility to make sure you are marketable. It is not your employer’s responsibility to train you, or to send you to conferences, or to buy you books. These things are your responsibility. woe to the software developer who entrusts his career to his employer.

Obvious, right? That’s what I thought for some time, but I was wrong. For my surprise, I’ve actually come to meet people who refuse to worry about any learning that takes place out of the 9 to 5 frame. I still like to think they are the minority though, but in any case, it’s always good to keep this in mind. Having an employer that gives you some of the things listed above is always cool, and nowadays you can find that in a lot of places, but remember, it is your responsibility, no one else’s.

SAYING NO

On “Saying No”, and the concept of trying:

The promise to try is an admission that you’ve been holding back, that you have a reservoir of extra effort that you can apply. The promise to try is an admission that the goal is attainable through the application of this extra effort.

Soon after followed by:

If you are not holding back some energy in reserve, if you don’t have a new plan, if you aren’t going to change your behavior, and if you are reasonably confident in your original estimate, then promising to try is fundamentally dishonest. You are lying. And you are probably doing it to save face and to avoid a confrontation.

Been there, done that. Never as a I lie, of course, but more as a product of my naivety in my first years. Fortunately for me, I’ve never had a this scenario in a big scale, and the amount of extra effort needed to try, wasn’t that much, so I was able to handle it. But the more I read those lines, the more I agree with them. While it’s true they are rather opinionated, there’s an underlying issue with them that is what really needs to be addressed in those situations: you’re probably trying to avoid a confrontation or a difficult situation.

CODING

On the act of coding:

Your code must be readable by other programmers. This is not simply a matter of writing nice comments. Rather, it requires that you craft the code in such a way that it reveals your intent. This is hard to do. Indeed, this may be the most difficult thing a programmer can master.

This doesn’t deserve much comment. You can see this idea all over the internet in articles, dev blogs, books, etc. If you tend to forget about it, print it out and stick it in your wall.

On pacing yourself:

When you are working on a problem, you sometimes get so close to it that you can’t see all the options. You miss elegant solutions because the creative part of your mind is suppressed by the intensity of your focus. Sometimes the best way to solve a problem is to go home, eat dinner, watch TV, go to bed, and then wake up the next morning and take a shower.

This looks like another one for the wall (ok, maybe a bit too long, but you get the point). I’ve made the mistake of not doing this more than once, and twice, and even if I managed to solve the problem at hand, I assure you that the solution ended up coming back to bite me. This is the simplest thing to do, yet many of us fall into the same trap over and over, that it’s always good to review it and make sure we put it in practice when the situation calls for it.

On hoping:

Do not hope that you can get it all done in ten days. Hope is the project killer. Hope destroys schedules and ruins reputations. Hope will get you into deep trouble. If the trade show is in ten days, and your nominal estimate is 12, you are not going to make it. Make sure that the team and the stakeholders understand the situation, and don’t let up until there is a fall-back plan. Don’t let anyone else have hope.

Don’t hope. Instead, communicate. If you communicate but feel the message is not being properly escalated, then communicate twice. If you’re still not sure, insist. But don’t hope. As they say, “plan for the worse, hope for the best”.

On rushing:

Woe to the poor developer who buckles under pressure and agrees to try to make the deadline. That developer will start taking shortcuts and working extra hours in the vain hope of working a miracle. This is a recipe for disaster because it gives you, your team, and your stakeholders false hope. It allows everyone to avoid facing the issue and delays the necessary tough decissions.

Again, this is a bit of a dogmatic one, but the principle is clear. In reality, in certain scenarios, there might be “some” (note the quotes) room for shortcuts. When the time comes for that, you’ll have to make trade offs in the product you’re building. My point is: never rush things, but if there’s such a time when you’re demanded to make some trade offs in favour of something else, make sure stakeholders understand what those trade offs are, what other implications will develop from them, and the follow up actions that will be required.

For example: You have to build a statistics / reporting server for a big site. The client needs the first reports as soon as… last week. You can get something build in a week that will give them most of the data they need in the short term, but is not scalable, will need refactoring, and will impact performance of the main application in the long term. For proper planning of the right solution, you might need 3 weeks. In fact, that’s the only solution, because the first one will put the main application in danger if it’s not moved into a separate platform after a few months. Well, explain, that to the client. 9 times out of 10 they’ll be happy to go with the first option, get the data they need, and right after that, plan 2 or 3 extra weeks to sort out the much needed refactoring to get things properly done.

On overtime:

Overtime can work, and sometimes it is necessary. Sometimes you can make an otherwise impossible date by putting in some ten-hour days, and a Saturday or two. But this is very risky. You are not likely to get 20% more work done by working 20% more hours. What’s more, overtime will certainly fail if it goes on for more than two or three weeks.

Soon followed by:

… The last criterion is a deal breaker. If your boss cannot articulate to you what he’s going to do if the overtime effort fails, then you should not agree to work overtime.

I’ve never thought about that last sentence before, but it’s something so true! If you’re going to work overtime, you’re on a tight deadline. So tight that indeed, even working overtime could fail. If that happens, the last thing you want to hear is that all your effort has mean nothing. If the deadline is so important to the business that they want you to work overtime, it surely is as important to have a fallback plan in case that fails. If such fallback does not exist, then the deadline doesn’t matter that much.

On false delivery:

Of all the unprofessional behaviors that a programmer can indulge in, perhaps the worst of all is saying you are done when you know you aren’t. Sometimes this is just an overt lie, and that’s bad enough. But the far more insidious case is when we manage to rationalize a new definition of “done”. We convince ourselves that we are done enough, and move on to the next task. We rationalize that any work that remains can be dealt with later when we have more time.

I’ve been on the suffering side of this. I don’t wish it to anyone. Please, never do this.

PRACTICE

In one way or another, all professionals practice. They do this because they care about doing the best job they possibly can. What is more, they practice on their own time because they realize that it is their responsibility – and not their employer’s- to keep their skills sharp. Practicing is what you do when you aren’t getting paid. You do it so that you will be paid, and paid well.

If the part about doing the best job you possibly can is not a motivator in itself, then proceed to the last sentence. Getting paid well is certainly a good motivator, isn’t it?

ACCEPTANCE TESTING

On premature precision and the uncertainty principle:

Both business and programmers are tempted to fall into the trap of premature precision. Business people want to know exactly what they are going to get before they authorize a project. Developers want to know exactly what they are supposed to deliver before they estimate the project. Both sides want a precision that simply cannot be achieved, and are often willing to waste a fortune trying to attain it.

The problem is that things appear different on paper than they do in a working system. When the business actually sees what they specified running in a system, they realize that it wasn’t what they wanted at all. Once they see the requirement actually running, they have a better idea of what they really want – and it’s usually not what they are seeing.

Probably not obvious, but quite true. That’s why the Agile way puts emphasis on having small iterations, schedule demos as frequently as possible, defining MVPs, etc. That will work much better than defining every single detail of an application upfront, which highlights the importance of being capable of guiding your clients through the definition of that MVP, to avoid the excess of details and fine-tuning in early phases of the project.

On estimation anxiety:

Professional developers understand that estimates can, and should, be made based on low precision requirements, and recognize that those estimates are estimates. To reinforce this, professional developers always include error bars with their estimates so that the business understand the uncertainty.

A lot of people would probably complain that clients want a fixed price. That’s true, and it’s true that simply producing estimates with error bars won’t solve that. But in a lot of scenarios, it will actually help. I’ve done this several times already, and most managers are happy to accept that I” think it’ll take me 5 days, but unknown elements X, Y and Z could take it up to 8 or 9 days, in the worst case”.

Also, being explicit about that will make them more concerned about what those X, Y and Z elements are (because, you know, money), and they’ll put more effort into removing them from your plate as soon as possible, than if you just estimate 8 days upfront and mention there are some blockers for which you’ll need help. Why? Because you already said 8 days.

TIME MANAGEMENT

On declining:

You do not have to attend every meeting to which you are invited. Indeed, it is unprofessional to go to too many meetings. You need to use your time wisely. So be very careful about which meetings you attend and which you politely refuse.

Nothing to add, but this is indeed something to have always in mind. You’re not doing anyone any good by accepting every single meeting you’re invited to. Don’t run away from them, but be aware of what’s your use in them, and when to leave them if you’re not needed anymore after some time.

PRESSURE

On commitments:

Sometimes commitments are made for us. Sometimes we find that our business has made promises to the customers without consulting us. When this happens we are honor bound to help the business find a way to meet those commitments. However we are not honor bound to accept the commitments.

COLLABORATION

Perhaps we didn’t get into programming to work with people. Tough luck for us. Programming is all about working with people. We need to work with our business, and we need to work with each other.

MENTORING, APPRENTICESHIP AND CRAFTMANSHIP

School can teach the theory of computer programming. But school does not, and cannot teach the discipline, practice, and skill of being a craftsman. Those things are acquired through years of personal tutelage and mentoring. It is time for those of us in the software industry to face the fact that guiding the next batch of software developers to maturity will fall to us, not to the universities. It’s time for us to adopt a program of apprenticeship, internship, and long-term guidance.

I won’t go into any thinking for this quote, although I liked a lot this reflection at the end of the last chapter of the book.

So, that was it. There were some more quotes I had listed to include here, but they didn’t seem to me as important as the ones I’ve selected. This is a unique book that, again, I’d recommend to everybody, and I suspect I’ll be revisiting it from time to time to review some things. Perhaps by then my opinion in some matters have changed, or perhaps it hasn’t.

Whether you agree with all the principles in the book is not really that important. I’m sure there’s a wide range of opinions in most of the subjects it touches. What is more important, from my point of view, is the fact that there is a code of conduct that questions bad and good practices and attitudes in our profession. The simple act of reading it, will take anybody into a process of reflection and self-critique, that it’s so important in every aspect of life, and I doubt anything bad can come out of that process.

 

Leave a Reply

Your email address will not be published. Required fields are marked *