Seeing that Uncle Bob is making a new version of Clean Code I decided to try and find this article about the original.
I felt the same when reading that book, and I never finished it because following the rules he suggested produced horrible code.
If memory serves, he also suggested that the ideal if statement only had one line inside, and you should move multiple lines into a function to achieve this.
I once had to work on a codebase that seemed like it had followed his style, and it was an awful experience. There were hundreds of tiny functions (most only used once) and even with an IDE it was a chore to follow the logic. Best case the compiler removed most of this “clean” code and the runtime wasn’t spending most of its time managing the stack like a developer had to do.
There’s nothing quite like the unique pain of navigating an unfamiliar codebase that treats abstraction as free and lines of code in one place as expensive. It’s like reading a book with only one sentence per page, how are you supposed to understand the full context of anything??
Haha, the horrors of trying to fix a bug in OpenOffice flash before my eyes
It’s abstract art!
There’s a piece of code in our hobby game project that I’ve written after attending classes in college about how to write clean and SOLID code. It’s the most overengineered piece of shit I’ve ever written. I’m not saying it’s the fault of the lectures, of course it’s on me being a little bit over zealous, but it does check all the boxes - It’s a simple “show selectable list of stuff”, follows MVC, it’s extensible without rewriting to adittional data-types and formats, extensible view that can show any part of data you need, generic, and in general it could be used anywhere we need, for any kind of data.
There’s only one place where we need and use such list in our game.
I needed to rewrite a part of it, since the UI changed drastically, to not need this kind of list, while also adding events into the process. I haven’t seen the code for almost 4 years, and it’s attrocious. Super hard to understand what’s going on, since it’s too generic, interfaces and classes all over the place, and while it probably would be possible to rewrite the views for the new features we need, it’s just so complex that I don’t have the mental capacity to again figure out how it was supposed to work and properly wire it up again.
I’m not saying it’s fault of the classes, or SOLID. It’s entirely my fault, because the classes inspired and hyped me with ideas about what a clean code should look like, that I didn’t stop and think whether it’s really needed here, and went over-the-top and overengineered the solution. That’s what I’d say is the danger of such Clean Code books and classes - it’s easy to feel clever for making something that passes SOLID to the letter, but extensibility usually comes at a complexity, and it’s super important to stop and think - do I really need it?
Academia has a disconnect with the industry when it comes to coding practices. Most teachers haven’t much industry experience. They don’t know how it is to maintain a 10 year old project using SOLID and clean code principles.
They just teach whatever has already been in the curriculum for decades. They don’t know that whatever they’re teaching is actually harmful in the industry.
Oh man, taking the reference code for an academic white paper and trying to add something to it is a trip.
Almost never any thought beyond proving the point of the paper.
Super hard to understand what’s going on, since it’s too generic
In other words, you wrote nice code, but forgot to document it?
That’s a good question, and I never through about it like that. I think that the lack of documentation isn’t that much of a problem, rather that the code stands out in the project in that it is complex to understand and requires some more though, effort and imagination to grasp, since it’s generic with lot of interfaces and polymorphism.
Now, that usually wouldn’t be much of an issue, however - the project is a game we’ve been actively working on in our spare time in a team of 2 programmers for the last 6 years, and we are all fed up with it and just want it to end. Most of the (pretty large by now) codebase is kind of simple - it’s a game code, after all, and since we started it when we were 20, there aren’t many overenginered ideas or systems, but everything is mostly written in the ugly, but simple and direct way, so if we had wanted to change something, we may have had to rewrite a part of it, but it never really needed much effort to understand what’s going on.
But now I need to change this code, which is one of the only parts that requires some kind of imagination and actually sitting down and trying to understand it, and since my motivation about the project is so low, it’s a pretty large hurdle to cross. One that is also unnecessary, since most of the generalism isn’t needed and will never be used. But since the code is written in such extensible way, it’s hard to just hack up a simple and ugly solution somewhere into it and be done with it, without really figuring out what the hell is going on.
A documentation wouldn’t help with that - it would still take the same amount of mental effort to be able to work with that code, which we generally lack in the project. I think that if I actually took the time to properly look through the code, figuring out what’s going on wouldn’t be too hard - the naming convention is pretty ok and it’s not that difficult, it just requires some mental effort.
I’m not trying to make excuses, the code very probably has problems, I’m just trying to better sort my thoughts about why I have so much problems working on it. It probably has more to do with my motivation, rather than the code in itself, and the fact that the complexity here wasn’t required, and is now a needless hurdle that actually hinders progress. Not due to it’s quality, but do to unrelated motivation issues and us having to basically force ourselves to work on and finish the damn project.
Is it possible that you just chose the wrong abstractions?
Usually it doesn’t matter what abstractions you choose when you try to factor them to support hypothetical future work, because chances are you incorrectly anticipate future needs.
In other words, generic code that only supports one use case will almost certainly have to be deconstructed to allow a good generic implementation for 2 use cases, so it is better to just write simple code and factor code out when you can see the real commonalities.
In other, other words, KISS, YAGNI
Good abstractions are important for the code to be readable. An AbstractEventHandlerManager is probably not a good abstraction.
The original commenter said that their code was “generic with lot of interfaces and polymorphism” - it sounds like they chose abstractions which hindered maintainability and readability.
I feel like it’s wrong to idolize anything in the same way that it’s wrong to throw out many things (there are some clear exceptions usually in the realm of intolerance but that’s unrelated to this). Clean Code, like every other pattern in software development, has some good things and some bad things. As introduction to the uninitiated, it has many good things that can be built on later. But, like Gang of Four, it is not the only pattern we apply in our craft and, like Agile, blind devotion, turning a pattern into a prescription, to Clean Code is going to lead to a lot of shit code.
Cognitive load helps us understand this problem a lot better. As a junior with no clue how to write production code, is Clean Code going to provide with a decent framework I can quickly learn to start learning my craft, should I throw it out completely because parts are bad, or should I read both Clean Code and all its criticism before I write a single line? The latter two options increase a junior’s extraneous cognitive load, further reducing the already slim amount of power they can devote to germane cognitive load because their levels of intrinsic are very high by the definition of being a junior.
Put a little bit differently, perfection (alternatively scalable, maintainable, shipped code) comes from learning a lot of flawed things and adapting those patterns to meet the needs. I am going to give my juniors flawed resources to learn from to then pick and choose when I improve those flaws. A junior has to understand the limitations of Clean Code and its failures to really understand why the author is correct here. That’s more cognitive science; we learn best when we are forming new connections with information we already know (eg failing regularly). We learn worse when someone just shows us something and we follow it blindly (having someone solve your problem instead of failing the problem a few times before getting help).
I’m gonna be super hand-wavy with citations here because this a soapbox for me. The Programmer’s Brain by Felienne Hermans does a good job of pulling together lots of relevant work (part 2 IIRC). I was first introduced to cognitive load with Team Topologies and have since gone off reading of bunch of different things in pedagogy and learning theory.
The article goes into that. Clean Code has some good advice. But it also got bad advice.
Problem is, the good advice is basic. Anyone working in the industry will pick most of these up. All the good advice could be summed up in 10 pages or so.
The bad advice is incredibly bad - and in the worst cases even be counter productive. A newbie won’t be able to tell these advice apart. Some professionals might not either. So they adopt these techniques to their code, and slowly their code turns into an unmaintainable mess of spaghetti.
So no, the book shouldn’t be recommended to anybody. It has already done enough harm to the industry.
As a junior with no clue how to write production code, is Clean Code going to provide with a decent framework I can quickly learn to start learning my craft, should I throw it out completely because parts are bad, or should I read both Clean Code and all its criticism before I write a single line?
I see what you’re getting at it, and I agree we shouldn’t increase the load for juniors upfront. But I think the point is mainly there are better resources for juniors to start with than Clean Code. So yeah, the best option is to throw it out completely and let juniors start elsewhere instead, otherwise they are starting with many bad parts they don’t yet realize are bad. That too would increase cognitive load because they would need to unlearn those lessons again.
Exactly. The article is pretty clear with this point. Junior devs aren’t the ones we should be giving mixed bags of advice to.
I’m all for it! What’s the resource that solves this problem?
It must be perfect since we can’t ever give mixed bags of advice. There are apparently better resources although I didn’t see one in the article and things like Code Complete and Pragmatic Programmer address a lot of the same things. Hell, we probably shouldn’t talk about The Mythical Man-Month anymore either. Do we also throw out Design Patterns since singletons are arguably bad design these days?
Literally no need for that level of sarcasm.
I took the things defined in the comments responding to mine and extended them. If we can’t share a mixed bag, all of the things I highlighted are out. It would be logically inconsistent to think otherwise starting from your conclusions. Either we have perfect resources or we have, as I called out, to pick and choose our battles. I want to see a perfect resource not ad hominem.
Edit: genuinely surprised to see someone on a CS instance not understand reductio ad absurdum/impossibile (depending on how you feel about Gang of Four)
Telling you that you don’t need to be sarcastic is not ad hominem.
Your response was to call my argument sarcasm. That is directed at me rather than what I said. That’s quite literally, not figuratively, the definition of sarcasm.
I wish you the best of luck. You don’t seem to be interested in the comments unless it agrees with you and you have yet to share a perfect resource. Have fun!
It’s inspired so many crimes against engineering as a whole that it’s OK to discourage people from reading it. Not only is it pointless, but it’s also actively harmful to the industry as a whole.
When something is mostly garbage and good advice is so sparse in it, there’s no need to hold onto it. It’s as much of a mixed bag as a turd with a nice ribbon is a mixed bag of prettiness.
Burn it with napalm.
… Nah, I don’t actually mean it should be burnt, that was a joke. The book is a nice reminder that, on top of being a bigot, Robert Martin (not my uncle) should not be hired to write any kind of code in any professional capacity.
IMO it would be best to present code that fits in a single file to people on the net and refactor it to their liking while keeping the same functionality, then let others rate the style and pick a few characteristics. Then the code can be ranked by the different characteristics to obtain the top 5 or so “cleanest” coding styles.
I feel it’s worth doing an entire study instead of relying on what one dude says is clean code. Let the people speak.
No, it isn’t
It makes me sad to see people upvote this.
Robert Martin’s “Clean Code” is an incredibly useful book which helps write code that Fits In Your Head, and, so far, is the closest to making your code look like instructions for an AI instead of random incantations directed at an elder being.
The principle that the author of this article argues against seems to be the very principle which helps abstract away the logic which is not necessary to understand the method.
public void calculateCommissions() { calculateDefaultCommissions(); if(hasExtraCommissions()) { calculateExtraCommissions(); } }Tells me all I need to know about what the method does - it calculates default commissions, and, if there are extra commissions, it calculates those, too. It doesn’t matter if there’s 30 private methods inside the class because I don’t read the whole class top to bottom.
Instead, I may be interested in how exactly the extra commissions are calculated, in which case I will go one level down, to the
calculateExtraCommissions()method.From a decade of experience I can say that applying clean code principles results in code which is easier to work with and more robust.
Edit:
To be clear, I am not condoning the use of global state that is present in some examples in the book, or even speaking of the objective quality of some of the examples. However, the author of the article is throwing a very valuable baby with the bathwater, as the actual advice given in the book is great.
I suppose that is par for the course, though, as the aforementioned author seems to disagree with the usefulness of TDD, claiming it’s not always possible…
I hate reading code like this. It means that there is a bunch of object or global state that could be getting modified by anything all over the place that I can’t see just by looking at the method. In other words, if you say you understand this method, it is because you are making assumptions about other code that might be wrong.
I’ll take a 30 line pure function over a web of methods changing member state every time.
Tells me all I need to know about what the method does
No, it only tells you what the method is supposed to do.
While that may be helpful it may also be misleading. It helps just as much as comments when debugging - and that probably is the most relevant reason for trying to figure out someone else’s code.
It also tells you nothing about the data flow or the data at all. What do these functions do? What data to they act on? It is all just pure side effects and they could be doing anything at all. That is far from what I consider clean.
“Show me your flowchart and conceal your tables, and I shall continue to be mystified. Show me your tables, and I won’t usually need your flowchart; it’ll be obvious.” – Fred Brooks, The Mythical Man Month (1975)
Why is it a
voidmethod? This only tells me that some state is mutated somewhere, but the effect is neither visible nor documented.I would expect a function called “calculate” to just return a number and not have any side effects.
You’re nitpicking.
As it happens, it’s just an example to illustrate specifically the “extract to method” issues the author had.
Of course, in a real world scenario we want to limit mutating state, so it’s likely this method would return a
Commissionlist, which would then be used by a Use Case class which persists it.I’m fairly sure the advice about limiting mutating state is also in the book, though.
At the same time, you’re likely going to have a void somewhere, because some use cases are only about mutatimg something (e.g. changing something in the database).
It’s not nitpicking, stuff like this is far more impactful than choosing between 5 lines vs 10 lines long methods, or whether the
hasExtraCommissions“if” belongs inside or outside ofcalculateExtraCommissions. This kind of thing should immediately jump out at you as a red flag when you’re reading code, it’s not something to handwave away as a detail.I never claimed it’s not important, I’m just saying it’s not relevant here, as there is no context to where this method was put in the code.
As I said, it might be top-level. You have to mutate state somewhere, because that’s what applications ultimately do. You just don’t want state mutations everywhere, because that makes bad code.
The whole book is like this, though, and these are specifically supposed to be examples of “good” code. The rewritten time class toward the end, a fully rewritten Java module, is a nightmare by the time Martin finishes with it. And I’m pretty sure it has a bug, though I couldn’t be bothered to type the whole thing into an editor to test it myself.
I really dislike code like that. Code like that tends to lie about what it says it does and have non-explicit interactions/dependencies.
The only thing I can really be certain from that is:
doAnything(); if(doAnything2()) { doAnything3(); }I.e. almost nothing at all because the abstractions aren’t useful.
You realize this is just an argument against methods?
All methods? Of course not. Just methods like these.
No, your argument is equally applicable to all methods. The idea that a method hides implementation details is not a real criticism, it’s just a basic fact.
These kind methods hide too much.
Where can I find the commissions these methods calculated? Does extra commissions depend on the calculations of default commissions? Do I need to calculate default commissions before calling hasExtraCommisions? What happens if I calculate extra commissions if hasExtraCommisions return false?
There are so many questions about this code that should be immediately obvious, but isn’t.
What you’re saying is “descriptive method names aren’t a substitute for knowing how the code works.” That’s once again just a basic fact. It’s not “hiding,” it’s “organization.” Organization makes it easier to take a high level view of the code, it doesn’t preclude you from digging in at a lower level.
What I’m saying is that it’s hiding too much of the control flow.
Compare it with this code:
public double calculateCommision(Sale sale, Contract contract) { double defaultCommision = calculateDefaultCommision(sale); double extraCommision = calculateExtraCommision(sale, contract); return defaultCommision + extraCommision; }This is about the same number of lines, but it communicates so much more about the control flow. It gives us an idea which data is involved in the calculations, and where we can find the result of all the calculations. We can make assumptions that the functions inside are independent from each other, and that they’re probably not relying on side effects.
This is also against clean code examples, because Uncle Bob seems to be allergic against function arguments and return values.
Robert Martin’s “Clean Code” is an incredibly useful book which helps write code that Fits In Your Head
It has the exact opposite effect. It leads to code that doesn’t fit in your head.
Because his style of coding leads to code where everything useful are 10 levels deep in nested method calls. If I want to understand how the code works and how my changes will affect the overall picture, I need to keep a dozen methods in my head and how all of these are connected to each other.
And he’s mostly working with global states, so knowing where variables are assigned is just a huge pain.
So many times I’ve looked into code like this where I finally find what I’m looking for, only to forget how I even reached this part of the code. So I need to backtrack to remember how I got there, but then I forget where that damn thing I was looking for is. And I go back and forth until I figure out a mental model of the code. It’s awful!
Compare that with just having one big method. Everything is in front of me. I don’t need to keep that many things in my head at the same time, because everything I need is right there in front of my eyes.
Sure, sometimes breaking out to separate methods can make it easier to communicate what the code does and the boundaries of each scope, but if it’s overdone it leads to code that’s impossible to work with.
Clean code does not prevent writing bad code, it just makes it a bit easier to write good code.
OF COURSE you can follow the principles and still write bad code, because so much more goes into it, including skill.
A giant method with everything laid out, potentially mixing abstractions sounds like a nightmare to me. It leads to cognitive overload.
I heavily disagree it’s easier to write good code if you follow clean code. Especially if you follow his examples throughout the book. Most of his examples are just over engineered messes held together by side effects (even if he says side effects is a bad thing).
If he can’t write good code by following clean code, why should you? He even picked the examples himself and failed!
in which case I will go one level down, to the
calculateExtraCommissions()method.In which case you will discover that the calculateExtraCommissions() function also has the same nested functions and you eventually find six subfunctions that each calculate some fraction of the extra commission, all of which could have been condensed into three lines of code in the parent function.
Following the author’s idea of clean code to the letter results in a thick and incomprehensible function soup.
It’s only as incomprehensible as you make it.
If there are 6 subfunctions, that means there’s 6 levels of abstraction (assuming the method extraction was not done blindly), which further suggests that maybe they should actually be part of a different class (or classes). Why would you be interested in 6 levels of abstraction at once?
But we’re arguing hypotheticals here. Of course you can make the method implementations a complete mess, the book cannot guarantee that the person applying the principles used their brain, as well.
Six levels of abstractions, sure, if you have that many, you may want 6 functions. But that contradicts Martin when he’s saying that there should be one line in an if, and everything more should be promoted to its own function. There’s no way a programmer routinely writes code so terse that you get six levels of abstraction in a dozen of lines of code. Otherwise, Martin doesn’t understand what an abstraction is.
Managing a stack in your head like a computer is very challenging as far as cognitive load is concerned. You don’t want to jump all over the place. Otherwise, when you reach your destination, you end up forgetting what got you here in the first place.
This form of code fragmentation makes debugging an absolute nightmare, and finding sources of mutation absurdly frustrating. Good tooling can help you track where a variable is used and in which order mutations happen trivially in code in a single function. It’s not as as helpful when it’s spread all over the place. You can infer so much less statically if you follow Martin’s advice.
I’m not advocating for 1000-lines functions here, mind you. When functions become too big, other challenges arise. What’s necessary is balance, which Martin’s book fails to teach.
Why would you be interested in 6 levels of abstraction at once?
Because there aren’t 6 interesting levels of abstraction. It’s like talking to a child:
What are you doing?
Finances
What does that involve?
Processing money.
What kind of processing?
Summarising
What kind of summaries?
Summaries of everything
What specifically though?
Summaries
Ok so you’re just displaying total balance then…
Because abstractions leak. Heck, abstractions are practically lies most of the time.
What’s the most time-consuming thing in programming? Writing new features? No, that’s easy. It’s figuring out where a bug is in existing code.
How do abstractions help with that? Can you tell, from the symptoms, which “level of abstraction” contains the bug? Or do you need to read through all six (or however many) “levels”, across multiple modules and functions, to find the error? Far more commonly, it’s the latter.
And, arguably worse, program misbehavior is often due to unexpected interactions between components that appear to work in isolation. This means that there isn’t a single “level of abstraction” at which the bug manifests, and also that no amount of unit testing would have prevented the bug.
How do abstractions help with that? Can you tell, from the symptoms, which “level of abstraction” contains the bug? Or do you need to read through all six (or however many) “levels”, across multiple modules and functions, to find the error?
I usually start from the lowest abstraction, where the stack trace points me and don’t need to look at the rest, because my code is written well.
Yeah, cause silly mistakes in one place never affect another place that’s completely unrelated.
That’s great, but surely, from time to time, you have to deal with code that other people have written?
I do, and whether I have a good time depends on whether they have written their code well, of which the book’s suggestions are only one metric.
I hear you, but here’s my experience:
I’ve had one coworker whose personal coding style actually somewhat resembled that in the Clean Code examples. He wrote functions as small as possible, used many layers of abstraction, and named everything very verbosely and explicitly.
Now, to be fair, I don’t think he did that because of Clean Code, and he also didn’t follow most of the good practices that Martin recommends. Most egregiously, he almost never tested things, even manually (!!). He once worked an entire weekend to finish something that I needed for my part of the project, and when he was done, it didn’t work, because he hadn’t actually run it at any point (!!!).
But even when his software did work, it was horrendous to navigate and modify, specifically because of that style of writing code. I know, because when he retired, I was the only person on the team who could deal with it, so his part of the project fell entirely on me.
Now, I’ve also had to work with code that had the opposite problem: short names, no abstraction. And a sort of “worst of both” codebase where the functions were exceedingly long and full of near-duplicate functionality, but overall there was a fair amount of modularity and abstraction.
But in my opinion, it was much harder to deal with the code that hid all of its weirdness behind layers and layers of abstractions, despite those abstractions being carefully documented and explicitly named.
Declarative, functional code is by definition much closer to ai prompts than any imperative code. Businesses are just scared of functional programming because they think that by adopting oop then can make developers interchangeable, the reality is that encapsulation is almost never implemented in a proper way and we should be instead focusing on languages that enforce better systems over slamming oop into everything.
Hell, almost every modern developer agrees that inheritance is just bad and many frown upon polymorphic code as well.
So if we can’t properly encapsulate, we don’t want inheritance or polymorphism, we don’t want to modify state, what are we even doing with oop?
No, not “almost every modern developer thinks inheritance is just bad.” They recognize that “prefer composition over inheritance” has merit. That doesn’t mean inheritance is itself a bad thing, just a situational one. The .NET and Java ecosystems are built out of largely object-oriented designs.
Folks really trying to argue about example code. Even created “global state” straw man. Here is secret - if you are using global state then code is shit in the most cases.
It’s not a strawman, though, because Martin’s actual example code in the book is like this, including a full module he rewrites toward the end.
When they say global state here it’s not really global state, it’s class members - global to the class. “Why are they calling it global state then, idiots?” you might think. It’s because it prevents local reasoning in the same way as global state does (and most people get the implications of “global state” because of experience, so it’s a kind of shorthand).
Of course, not many people would recommend “no class variables” (in a classic OOP language anyway), but the point is they have similar downsides to global variables in terms of understanding code (and testing, etc.) so recommending to always use them - even when passing state in and out of functions is perfectly ergonomic - is clearly bonkers.
I can’t judge this example without seeing what would be inside those other methods. As presented, what you say makes sense, but many of the full examples shown in the article show very strange combinations.
I agree that private methods can help make code “fit in your head” but at the same time, dogmatically pursuing this can spread code out more which does the opposite.
If those functions are huge units of work or pretty complex, I can agree. For most cases though, a simple code comment should do to explain what’s going on?
Comments should never be about what is being done. They should only ever be about why it is being done.
If you write your code like suggested in the book, you won’t need to rely on possibly outdated comments to tell you what’s going on.
Any comment about “what is being done” can be replaced with extracting the code in question to a separate, well-named method.
I disagree about comments should never be about what is being done. If what is being done is not obvious then they’re important. Take assembly code as an example. Or complicated bit operations. I agree the why is more important to document than the what but saying the what is never important seems misguided.
Also, this may be a semantics thing, but oftentimes the code’s specification is in doc comments. I don’t believe you’re claiming code shouldn’t ever have specifications, this isn’t meant as a gotcha lol.
You’re talking about assembly in a thread about OOP…
I think commenting what can be important in OOP too though.
I think it’s good to document why things are done, but extracting things out into another function is just documenting what is being done with extra steps. This also comes with a number of problems:
- Not all languages are readable. Documenting what is being done is important in some C, or when working with some libraries that have confusing usage syntax.
- Not all people reading the code know the language or libraries well. Those people need guidance to understand what the code is trying to do. Function names can of course do this, but…
- Not all types can be named in all languages. Some languages have a concept of “opaque types”, which explicitly have no name. If parameter and return types must be specified in that language, working around that restriction may result in unnecessarily complicated code.
- Longer files (the result of having dozens of single-use functions) are less readable. Related logic is now detached into pointers that go all over the file all because of an allergic reaction to code comments, where a simple
//or#would have made the code just as readable. - Function names can be just as outdated as code comments. Both require upkeep. Speaking from personal experience, I’ve seen some truly misleading/incorrect function names.
A function name can be misleading just like a comment can, in the same scenarios and for the same reasons, plus it’s harder to update because you have to change it in at least two places.
And yet, outdated comments are far, far more common than outdated function names.
Also, if you’re changing a comment which explains the “what”, you should likely change the method name, as well.
It’s important for the client to know what the method does by looking at the name, so why would you duplicate your effort?
And yet, outdated comments are far, far more common than outdated function names.
Because people don’t try to squeeze a complete description of what a function does into a single identifier, which is what you you would have to do if you want function names to take the place of comments. I for one don’t want to strip all the spaces and punctuation out of my comments so I can use them as function names, and I really didn’t want to read someone else’s code written in that style.
