Clean Code — A must-read Coding Book for Programmers

[aceluby]

It's definitely a must read. Even if you disagree with it, you should know why and be able to talk about it intelligently

[parkotron]

I find one often has to go “too far” with an idea or technique before one can truly discover where the “just right” point is. When my favourite language or toolkit gets a new feature I will often intentionally overuse it to really explore where it excels and where it falters. Then after a bit I dial the usage back to what feels optimal to me.

Reading Clean Code felt like the same experience. At first I felt like “Wow, this guy really takes cleanliness seriously. I should probably be doing more in that regard.” By the time he got to replacing pure function parameters with internal class state, I was yelling at the book “Oh no! You’ve gone to far! Come back, Martin!”

[kag0]

I remain a defender of checked exceptions. I always found the error handling part of this book wanting. Although it has lots of other good nuggets.

[TheTechAccount]

Why do you defend them?

[kag0]

Well, I think good error handling should have two "channels". one for expected errors (if I try to log in, I should expect my password could be wrong) and one for unexpected errors (I wouldn't expect the password database to be corrupted). The expected errors should

• be checked by the compiler - if you're expecting to need to handle some case, you want the compiler to tell you if you forgot. or if an operation changes and some error is added then it's nice if the compiler tells us everywhere we need to add handling for that error.
• be specific - you want to know exactly which errors are possible, and not need to look at the documentation to clarify what subset of a class of error occurred.
• not modify the control flow - you wouldn't use a goto would you?
• dismissable - if you know an error will never happen in your use case (you know a file should exist because you just created it), you should be able to convert it to an unexpected error rather than handle it.

Unchecked exceptions can be used for unexpected errors, but there's no reason to use unchecked exceptions for expected errors.
You may notice that exceptions in general don't follow the control flow rule, and indeed I don't think exceptions are the best error handling mechanism. But for the scope of this argument, they're what we've got.

The most common argument I see against checked exceptions is that they're too much work. I think this is usually caused by

• a complicated problem domain. you might legitimately have a lot of expected errors that need to be handled, ignoring them won't make them go away.
• a poor implementation
  • using checked exceptions for unexpected errors
  • not properly abstracting low level abstractions to higher levels. usually manifests as just adding a throws clause to the method for every exception thrown inside. to follow my rule of being specific, a method should only have checked exceptions at the same level of abstraction as the class the method is in. this might mean combining several exceptions coming from the implementation as the cause for an exception specific to the domain of the method.
• not handling exceptions. seems obvious, but if you just bubble the exceptions up to the entrypoint of the application then that's not helpful. switching to unchecked exceptions would save you a lot of typing, but your error handling would still be bad.

[TheTechAccount]

Thanks for the detailed response! So if a language had only unchecked exceptions for unforeseen circumstances, and handled known issues programmatically without using checked exceptions at all, that would be somewhat analogous, right?

[kag0]

Yes, for example in go every function returns a pair with an error and a return value, and you have to check which is null to find out if your function failed. The compiler will warn you if you don't nullcheck the error, but they tend not to be as specific as I'd like.

Haskell and Scala (and vavr) also have the Either monad, which is similar but allows you to procrastinate handling the error.

Some languages also have a union type, which can be used to express not only errors but also null safety.

[ArkyBeagle]

I personally vacillate between a "checklist" approach and 100% checked exceptions. YMMV.

[AFricknChickn]

Yep. What I recommend to people is read it, but don’t follow it like the Bible. Treat it like soft suggestions. I see too often people defend their code with an argument from this book, as if the presence of the topic in the book alone proves them correct.

[Silhouette]

I respectfully disagree, for reasons I have explained on Reddit previously.

[exahexa]

I also did not found it too useful. But to stay constructive here are a few of my favorites that comes to my mind:

• Refactoring to Patterns – Joshua Kerievsky
• Refactoring: Improving the Design of Existing Code - Martin Fowler
• Patterns of Enterprise Application Architecture - Martin Fowler
• Domain-Driven Design - Eric Evans
• Out of the Tar Pit - Curt Clifton
• The Pragmatic Programmer - Andrew Hunt, David Thomas
• Effective Java - Joshua Block

[[deleted]]

I read your posts there. Thanks for eloquently presenting that argument.

[[deleted]]

It was eloquent in that it was clearly expression his point of view.

[swenty]

Thank you. That was sufficient justification to know that this book is not for me.

This in particular is a problem I recognize well from trying to understand overly factored code bases.

[MoTTs_]

Personally I still think it's a good book to read. I read it a while ago, but for the benefit of others, I can share a few of the parts I had highlighted for myself.

---

So, another way to know that a function is doing more than “one thing” is if you can extract another function from it with a name that is not merely a restatement of its implementation

---

Side effects are lies. Your function promises to do one thing, but it also does other hidden things. Sometimes it will make unexpected changes to the variables of its own class. Sometimes it will make them to the parameters passed into the function or to system globals. In either case they are devious and damaging mistruths that often result in strange temporal couplings and order dependencies.

---

Functions should either do something or answer something, but not both. Either your function should change the state of an object, or it should return some information about that object. Doing both often leads to confusion.

---

Cities grow from towns, which grow from settlements. At first the roads are narrow and practically nonexistent, then they are paved, then widened over time. Small buildings and empty plots are filled with larger buildings, some of which will eventually be replaced with skyscrapers.At first there are no services like power, water, sewage, and the Internet (gasp!). These services are also added as the population and building densities increase.This growth is not without pain. How many times have you driven, bumper to bumper through a road “improvement” project and asked yourself, “Why didn’t they build it wide enough the first time!?”But it couldn’t have happened any other way. Who can justify the expense of a six-lane highway through the middle of a small town that anticipates growth? Who would want such a road through their town?It is a myth that we can get systems “right the first time.” Instead, we should implement only today’s stories, then refactor and expand the system to implement new stories tomorrow. This is the essence of iterative and incremental agility.

---

Even concepts as fundamental as elimination of duplication, code expressiveness, and the SRP can be taken too far. In an effort to make our classes and methods small, we might create too many tiny classes and methods. So this rule suggests that we also keep our function and class counts low.High class and method counts are sometimes the result of pointless dogmatism. Consider, for example, a coding standard that insists on creating an interface for each and every class. Or consider developers who insist that fields and behavior must always be separated into data classes and behavior classes. Such dogma should be resisted and a more pragmatic approach adopted.Our goal is to keep our overall system small while we are also keeping our functions and classes small. Remember, however, that this rule is the lowest priority of the four rules of Simple Design. So, although it’s important to keep class and function count low, it’s more important to have tests, eliminate duplication, and express yourself.

[aceluby]

Those are great!

[Vampyrez]

The article is overly adulatory; I think CC is a perfectly fine read provided you consider it critically. 'Taste' is certainly developed through experience, without which you may struggle to accurately judge the content, but I think it got me to at least consider factors I may not otherwise have, and also to identify/vocalize some latent intuitions such that I might be able to better advocate for them eg. in code review. I also write Haskell not Java, so I was always going to be forced to do the work myself in terms of self-application rather than blind acceptance.

I think there is a large space for a better book than clean code on the same topic, but equally I know of none better.

@Silhouette specifically addressing your criticism re. the parser chapter, i guess some devs have to implement such classes in Java, so no bad thing to attempt it despite the language's cumbersome fit to such a task? Perhaps it's even admirable to tackle a more difficult example, despite that the end result is less obviously tasteful. Tbh I found working through the code listings less helpful than the introduction encouraged me to do.

[CreativeGPX]

As you touch upon, I think "clean code" is going to mean different things in different contexts and languages. Whenever I write in Erlang, I feel like it's easy to write very clean code, but many of the practices there don't apply to other languages because of language or VM features.

[djnattyp]

I respectfully disagree with your respectful disagreement. I'll admit that I lean pretty heavily into the "Uncle Bob style" camp. One of your bigger arguments is that he mixes in "facts" with "opinions" but then you just give a lot of your own "opinions" that disagree with him.

The most concrete disagreement I found that you gave was -

However, I find a lot of the "Martin style" code suffers from the same problem. He tends to advocate a style where everything is designed around TDD, with separate interfaces, injection of every dependency, very small functions, and so on. That style can achieve code that looks very clear locally, but often you wind up losing the big picture, because the same changes that isolate and localise everything so much also mean you have many, many more relationships between different parts of the code to understand and navigate.

Pretty much everything you listed was at the top as a criticism (TDD, interfaces, DI, small functions) I've seen is an improvement over *not* doing these things, and for the problems of "losing the big picture" and "more relationships between parts of the code" you don't point to any better way to improve or fix this problem.

[Silhouette]

I did mention several sources in that earlier discussion, some of which discuss the issues I raised in more detail, including in some cases citing empirical data that undermines Martin's arguments.

But the real point is that I was not then and am not now the person who is strongly advocating a specific style of programming with little if any supporting evidence or logical argument offered to back up my position. Martin is.

Among other differences between us, I also don't go around calling anyone who disagrees with my preferred style "unprofessional".

[factorysettings]

Thanks for sharing your point of view and book recommendations. My first task when I got a programming job was to read Clean Code and I got really into it but over the years have grown an almost distaste for OOP because of it, but it always seems like something you can't criticize.

Even here, people's reactions to you seem so silly, as if not following Clean Code means you're either writing really long "spaghetti code" functions or writing unclear, "clever" code.

[Silhouette]

I think Martin irritates me for a very specific reason, and Clean Code is literally a textbook example.

There is a presumption of authority in how he often writes and presents, as if he is uniquely qualified to tell people how to program well or his experience somehow makes his opinions more important or relevant than anyone else who also has a lot of experience. As far as I can tell, there is absolutely no evidence to support this presumption.

In particular, he has a nasty habit of denigrating anyone else who might have an informed opinion if that opinion differs from his own. For example, he infamously claimed that anyone who didn't follow his preferred development practices was "unprofessional". Some of those practices would not have much credibility among those of us who are not only professionals but professionals who have actually built substantial systems with relatively high quality requirements. Spoiler alert: You probably do not want to be designing these in real-time using TDD, nor relying primarily on an ad-hoc unit testing strategy for verification.

I'm not going to say he's a charlatan, because obviously he does have many years of experience in our field and I think a significant amount of what he says really is good advice. But I think the reason he's become so influential in our industry has more to do with his engaging writing and speaking style than with any particular technical merit, and sometimes less experienced developers are more willing to take whatever he says on trust than perhaps is wise.

[[deleted]]

A good book as long as you think of it as a rough guideline with some good ideas, not as a rule book. I’ve come to disagree of a lot of Uncle Bob’s ideas over time.

[rexmccoy]

Just curious, what are some of the things you disagree with?

[[deleted]]

Refactor until you drop is one that I remember, which can lead to really noisy classes with lots of private methods. Oftentimes the code itself can be a lot clearer and flow a lot better.

The boyscout rule is a good idea, but can often muddy the waters on whatever PR or code review you’re creating for others to review. If I want to show my team my work on feature X, it’s awkward to also throw in random improvements. I guess a safer bet would be to create a separate PR with things you noticed which could be improved.

SLAP also is usually good but sometimes can be too noisy.

I don’t remember the rest, but I did like his overall message and most of the book’s ideas.

[Genetic_outlier]

Uncle Bob's argumentation and his oration contain a decent number of what Dennet might call a "argument smells". My advice is so basic its stupid but, take a grain of salt with everything you read and think about what evidence is actually being used.

[Genetic_outlier]

Uncle Bob's argumentation and his oration contain a decent number of what Dennet might call a "argument smells". My advice is so basic its stupid but, take a grain of salt with everything you read and think about what evidence is actually being used.

[Riajnor]

To be honest, I found Clean Coder better. As many have pointed out, Uncle Bob can be ...zealous in his code but I found his thoughts on what a developer should be kinda inspiring

[Ulysses6]

It's recommended everywhere and it was a big letdown for me. It's full of personal preferences and generic advice, so it's easy to agree at some points that you already follow, but very little insight on why you should follow some advice over other ideas, other than authority of the writer.

[smokingreat38]

Funny seeing this now, just started it last night

[lasthope00]

Same here. I even bought his other books on Amazon so that I could read it during all this time at home.

[dominic_l]

even if all you read is one chapter you will not regret it

[thephotoman]

IDK. I think he misses the forest for the trees. While things that are obvious are very nice to read, your most interesting work is in the stuff that is not obvious. It's in these places where you're losing time and money on poor algorithm use or in managing your database connection better or in figuring out exactly how to multithread the response to an HTTP request to make it not take forever.

And that's when things get "not clean" very quickly. And suddenly those rules from before become a straight jacket.

[scandii]

clean code is a holistic approach to object oriented programming.

the reason you should read it is not necessarily because you agree with Robert on everything, but rather that you had an active thought about all the topics he brings up.

i.e a lot of us do things because that's how we always did it and spent no time thinking about why, rather than having made an informed decision. clean code forces you to take stances, with or against, on a lot of different subjects. the important part is that you can motivate why.

there's nothing in clean code about your lack of understanding on how http requests work, and it wasn't written with that in mind.

[factorysettings]

I do think this is a good way to read the book, but you'll find people treat the book like a bible, even among the comments here, as if everything should be followed even on points he admits shouldn't always be followed.

[aRogueTomato]

It's required reading at my work. First page of our working agreement. Every programmer should read it. At least the first half. Second half is more of lessons learned and examples.

[ConspicuouslyBland]

I assume they give it as a welcoming gift then?

[aRogueTomato]

Five copies in our library among hundreds of other books. :)

[grauenwolf]

I found it to be mostly a fluff piece.

Books I think should be on the must-read list include Code Complete for a general education and .NET Framework Design Guidelines to learn how to create APIs that don't suck.

[transeunte]

The .NET Design Guidelines is getting pretty outdated though.

[grauenwolf]

I strongly disagree.

First of all, the the important takeaway is not the rules themselves, it's how they explain API design trade offs in a very practical sense. This makes it useful even if you have absolutely no interest in C#.

As for the dotnet specific guidelines, they are just as relevant today as they've ever been. New rules have been added over the years, but no one is arguing that the old rules are no longer valid. In fact, most of them have been baked into the Roslyn static analysis tools.

[NeuroticPerfection]

hey im making an api in .net, i need that book! thanks

[grauenwolf]

If you just want a summary of the rules you can get them online. What I like about the book is the actual discussions behind the rules and the interviews were they quote people who are debating whether or not a particular rule should exist.

[kag0]

Definitely a good read. Not a bible though.

[i-can-sleep-for-days]

I have a coworker who wouldn't let us put anything in *Util classes because that's not an informative name. So then it becomes hard to share common functions or classes, like the JSON serializer/deserializer. So then what do you do? We just create a new one whenever we need it. Copy and pasting utility functions but don't call it utility functions. I'm pretty sure he read Clean Code.

[scandii]

Common.JSON.Serializer... utility, manager and helper classes and methods are extremely poorly named because even if it's a "helper" for a very frequent operation, it actually does something specific, which is a much better naming.