It's probably time to stop recommending Clean Code @ Things Of Interest
It's probably time to stop recommending Clean Code @ Things Of Interest
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.
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.
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)
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.
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).
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.
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.
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.
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.
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.