Clean Coder

Who is Robert C. Martin?

Robert C. Martin is a legend in the development industry. Commonly referred to as simply “Uncle Bob”. He is a software consultant and has been programming since the mid 60’s. Over the years he has written many books (some listed below) as well as shared his great knowledge of system design and coding best practices.

Designing Object-Oriented C++ Applications
Patterns Languages of Program Design
Extreme Programming in Practice
Agile Software Development: Principles, Patterns and Practices
UML for Java Programmers
Clean Code: A Handbook of Agile Software Craftsmanship
The Clean Coder: A Code of Conduct for Professional Programmers

The last book in that list is the focus of this post.

What’s it all about?

Well, I’ve taken the liberty to reference the author directly here as I feel his words convey the book’s focus more than I ever could…

I presume you just picked up this book because you are a computer programmer and are intrigued by the notion of professionalism. You should be. Professionalism is something that our profession is in dire need of. I’m a programmer too. I’ve been a programmer for 42 years (longer by the time you read this); and in that time I’ve seen it all. I’ve been fired. I’ve been lauded. I’ve been a team leader, a manager, a grunt and even a CEO. I’ve worked with brilliant programmers and I’ve worked with slugs. I’ve worked on high-tech cutting-edge embedded software/hardware systems, and I’ve worked on corporate payroll systems. I’ve programmed in COLBOL, FORTRAN, BAL, PDP-8, PDP-11, C, C++, Java, Ruby, Smalltalk, and a plethora of other languages and systems. I’ve worked with untrustworthy pay check thieves, and I’ve worked with consummate professionals. It is that last classification that is the topic of this book. In the coming years I would be fired from one job for carelessly missing critical dates, and nearly fired from still another for inadvertently leaking confidential information to a customer. I would take the lead on a doomed project and ride it into the ground without calling for the help I knew I needed. I would aggressively defend my technical decisions even though they flew in the face of the customers’ needs. I would hire one wholly unqualified person, saddling my employer with a huge liability to deal with. And worst of all, I would get two other people fired because of my inability to lead. So think of this book as a catalog of my own errors, a blotter of my own crimes, and a set of guidelines for you to avoid walking in my early shoes.

Take responsibility

A professional takes responsibility for his code and his decisions. His primary focus should be to ‘do no harm’.

Don’t harm the code:

Here is a short-list of things a professional will do…

Ensure that QA (Quality Assurance) find nothing wrong. If there are bugs then a professional will take note of them, how they occurred and aim to prevent it from happening again. A professional doesn’t rely on others to catch bugs for them.
Know how all the code works (even the bits they didn’t write). Understand all of the codebase and how the different components inter-lock. The only way a professional can apply an appropriate solution is to know the environment, its limitations and constraints.
Write tests (unit & acceptance) and will ensure they are automated. A professional who writes tests first before code will be more confident in adding new features and refactoring existing code as they have the tests to back them up as they make changes (especially if the tests are automated then the red/green/refactor cycle can be tightly integrated into the professionals work flow).
100% code coverage (or at least in the 90% range). TDD (Test Driven-Development) means that the code design allows every line of code the professional writes to be easily testable.

Do not harm the code’s architecture/structure:

A professional will keep in mind the following…

Software should be easy to change.
Making a change to the code base should be easy. If it isn’t then the professional will look to change the design of the code to accommodate this requirement so the code becomes more flexible and allows changes to be made more easily in future.
Any code the professional reads over or makes a change to will be analysed for any potential improvements to the code’s structure (this is known as ‘merciless refactoring’ or ‘the boy scout rule’). In other words always commit back a module in a better state than you originally checked it out.
Make continuous changes to the code base. Constantly changing the code (i.e. improving it) should result in greater flexibility and modularity. If you leave the code static (e.g. you’re afraid to change it in case it breaks something) then when management requests a change or new feature you may likely find the code is too rigid to be adapted.
Don’t be afraid to constantly change your code. Your tests are there to back you up and should be quick to run!

Work ethic

Your career is your responsibility, do not leave it up to your employer to train you, send you on courses or buy you books. Take control of yourself.

The time you spend at work should be spent on your employers problems, not yours. A professional works hard for his employer and makes time for his ‘career’ in his own time. This also doesn’t mean you should spend all your time on your career. You have a family/life too. Balance your work, your career and your life in appropriate measures.

Know your field

Professionals not only know their chosen favourite technologies, but have an understanding and interest in other technologies outside of that circle.

Professionals will know past techniques (and why they may no longer be relevant) as well as the current best practices.

Professionals will also know the pros and cons to specific techniques and when to choose one over the other.

Uncle Bob makes a comment which references the “Santayana’s curse”…

Those who cannot remember the past are condemned to repeat it.

Here is a short list of things you should know (or at least be quite familiar with):

Design patterns (GOF 24 patterns)
Design principles (SOLID, DRY, SRP, DIP)
Methods of working (Agile, Scrum, Kanban, Waterfall)
Disciplines (TDD, BDD, OOP, CI, Pair Programming)
Artifacts (UML, sequence diagrams, flow charts, decision tables)

Stay current

Practice. Doing your job isn’t practice. Your job helps you improve your current skills, practice is learning new related skills.

Professionals will participate in Code Katas. These aren’t about solving problems because as a professional they would have already solved the problems presented in the kata. The purpose of code katas for a professional is to help warm them up for the days work and as a warm down at the end of the day. It allows them to try out different options for refactoring the solution and finding other shortcuts.

Collaborate

A professional will plan, design and write code together with their team/co-workers. This helps open their knowledge up to new ways of thinking and solutions they may not have considered otherwise. This also facilitates faster learning and making fewer errors.

Mentoring

Nothing demonstrates more how much you know about a subject than when you try to teach it to some one else. Juniors will ask all sorts of questions you may have long forgotten about (such as why you no longer build something in a certain way or using a certain technique). Professionals look after juniors and don’t let them struggle on without help and direction.

Know your domain

A professional will research the business they are now building software for. So if you work for a travel agent then you should know a bit about that industry. You don’t need to be an expert, just know enough to recognise concerns with certain technical requests or specifications.

Identify with your employer

Effectively your employers problems are your problems and so you need to take their perspective and understand the features they want implemented. A professional will be in a better position to advise whether those new features are actually right for the business.

Learn to say no

If your boss tells you to implement a feature by a certain date and you know that can’t happen without compromising the quality and stability of the software, then be vocal and say “no, that’s not possible”

A professional wouldn’t flat out say “No” and walk away, they would suggest a date that the work could be completed by, or possibly a compromise in the features that would be implemented by the deadline date. A professional will work with management to agree on what’s achievable but won’t settle for intimidation because management has tried to enforce an unrealistic request.

As a professional you were hired to carry out a specific specialised job and it’s your responsibility to educate management on what’s feasible or not. Do not find yourself agreeing to impossible deadlines or saying “I’ll try” (I’ll try is usually interpreted by management as “yes”). Generally developers will agree to “try” because they want to avoid confrontations but it suggests that the work you were doing previously wasn’t’ actually your all.

What does “I’ll try” actually mean any way? That you’ll work longer hours or work weekends? No, of course not. So why tell management you’ll “try” when you’re just going to go ahead and do what you was planning on doing before. It will just let them down when you don’t succeed to finish by the deadline because management will have interpreted your “I’ll try” as “I will”.

Rules and principles for coding

A professional has a specific set of principles when it comes to how they work…

Professionals are prepared (always focused and understanding)
Professionals don’t write code when tired or distracted as this just results in code that doesn’t work or will just need to be rewritten later.
Professionals avoid “the zone”. This sounds controversial as “the zone” is what most developers think gives them their edge. That sweet moment where everything seems to be flowing just right. But “the zone” just tricks you into thinking the speed you’ve gained processing problems means they are really efficient. They aren’t. You lose the bigger picture when you get into the “flow”. So don’t buy into it. Be focused.
Professionals don’t code while listening to music. You aren’t as productive as you think you are. This is something I’ve personally experienced and agree with. Working in silence may seem boring or too solitary but I do my best work when the background noise disappears.
Professionals handle interruptions politely and be willing to help regardless. Have you ever given an agitated response to someone who has interrupted you while working? Your snappy response could be because you’re trying to figure out a complicated problem that requires total concentration (maybe you were trying to get “into the zone”). But a professional knows how to politely handle the situation and return to the problem at hand.
Professionals know that “writers block” can usually be solved (or alleviated) by pair programming.
Professionals know to produce creative output they need creative input. It’ll be different for each individual but find out what gets your creative juices flowing and make sure you indulge that as often as possible to allow your more creative output to flow.
Professionals avoid time fixing bugs. No other profession would stand for bugs in this way too long (could you imagine a doctor who made mistakes in diagnosis on every patient? he wouldn’t last in this profession very long!), so a software professional should aim to reduce debugging time to zero.
Professionals aren’t afraid to go home when there is a bug they can’t solve. They recognise their creative periods, and so know when to take a break. You’ll find that your subconscious will figure out the solution while your brain takes a rest - so remember that it’s ok to walk away and take a break.
Professionals know that being late for a deadline is a fact of life and unavoidable. But a professional will constantly measure their progress and inform those who need to know as early as possible if they’re not going to make the deadline. Don’t let people down at the last minute.
Professionals don’t give false hope that a deadline will be met if there genuinely is no chance. Better to formulate a fall-back plan or agree what can be achieved. Stick to your estimates, don’t let a manager try to convince you to “do what it takes” to make the deadline.
Professionals don’t build a wall around their code. Any developer should be allowed/able to make changes to other developers code.
Professionals understand that pair programming is a good thing in that it helps you learn the system, find bugs faster and share knowledge more efficiently.

Acceptance Tests

Acceptance tests help avoid ambiguity in feature requests and how the existing system functions. They are different from unit-tests (which test individual components of the code) in that they ensure the finished application functions how the business expects it to (without the business having to understand the technical aspects of the system).

These types of tests should be co-written by a stakeholder & a programmer to ensure clarity and accuracy, and they should always be written so they can be executed automatically.

Acceptance tests provide the entire team with the definition of “done” (e.g. code written, tests passing, code deployed & QA satisfied).

Professionals should never be passive-aggressive when it comes to acceptance tests. By this we mean: if you’ve been asked to implement a test that you think is faulty then it is your responsibility as a professional to make the business understand why the test is faulty and to come to an agreement on what an acceptable test should be. So don’t act passive-aggressively (in a “well if this is what they wanted, then this is what they’ll get” way) by allowing a faulty test to pass.

Managing time

A professional knows how to manage their time.

Meetings

They don’t go to every meeting they are invited to just because they’re invited. They only go to those meetings that affect the immediate job they’re working on.

The people who invite you to meetings aren’t responsible for managing your time, you are. Be wise about the time you give up as it otherwise will mean your work won’t get done.

A good manager will do what they should to keep you out of meetings.

If a meeting gets boring: leave. It’s unprofessional to stay in a meeting where your input is not needed. Be polite and excuse yourself.

Only agree to attend meetings where a clear agenda has been determined.

Scrum

Participates in a Scrum stand-up meeting should spend no more than 20 seconds per question (what did I do yesterday, what am I doing today, what’s blocking me)

Sprint Planning

Sprint Planning sessions are a notoriously difficult part of Agile to get right. But effectively: estimates for backlog items should already be done, ready for selection/rejection. Ideally acceptance tests will also have already been written. No more than 10mins should be spent reviewing any item. If more time is needed then another meeting should be scheduled with a subset of the team to discuss further.

Sprint Retro

Sprint Retro should only take 20mins and your sprint demo should only take 25mins. For most Agile teams it will only have been two weeks since your last retro so there shouldn’t be that much to talk about.

Discussions

Any argument that lasts longer than 5mins can not be settled by arguing. Get data to back up your opinions and to solidify a decision.

Code

Avoid blind alleys. A blind alley is where you choose a technical solution and stick with it even though later on you realise it’s not the right choice. Learn to stop digging that hole. Back out and try something different.

Avoid messes. A mess is like a time black hole that sucks you in. Every step you think you’re closer to the finish, and it seems to be better than starting over. Don’t fall for it!

Blind alleys and messes have very subtle differences but basically both should be recognised as early as possible so you can escape them.

Estimations

A professional will try not to estimate a job by themselves. Any one who does this should expect to go over by at least 3 times as long as their original estimate.

Professionals will estimate with the help of their team as they know someone on the team may highlight an issue the others (including yourself) have missed or not considered.

If appropriate, try breaking up a task into smaller tasks and estimating each smaller task. In doing so you’ll likely find that the total sum of your estimate is larger than your original estimate would have been for the whole thing (i.e. before you split the task into smaller chunks).

Pressure

A professional knows to stay calm under pressure.

A clear head is essential. No good comes from pent up frustration at management for tight deadlines, or poor software (when a build breaks just before going live).

A professional resorts to discipline and training to get through these situations.

Ultimately: by handling your job and your responsibilities professionally you’ll be able to avoid pressure by avoiding situations that cause pressure.

Conclusion

This has been a bit of a whirlwind tour of “The Clean Coder: A Code of Conduct for Professional Programmers” but hopefully you’ve learnt a few things about how to handle yourself in a professional manner and will want to pick up the book to get the full benefit of “Uncle Bob’s” experience and advice.

I cannot recommend this book enough. I can see it being a useful tool for not only developers but for managers as well, because although the book is primarily focused on people in the software engineering industry, the information and tips are still relevant cross-discipline.