It's probably time to stop recommending Clean Code (2020)
qntm.org
qntm.org
I almost never want to use the word “clean” when I’m talking about code.
These days, when someone asks me to review code, and they start talking about “clean” code, I shift the discussion to two points—code should be correct and easy to understand. I think “correct and easy to understand” is a much more useful rubric than “clean”. Obviously it’s still subjective. Code that is easy to understand for you may be hard for me to understand. Likewise, code that is correct for your use cases may be incorrect for my use cases. But it’s much easier to come to an agreement about “correct and easy to understand”, or at least communicate issues with the code using that basis.
Like, “you shouldn’t use boolean flags as parameters, you should use enums” becomes “I can‘t understand the meaning of true/false at the call site, so let’s use an enum instead”. This gives us a very clear, articulable basis for how we talk about code quality.
Of course, “correct and easy to understand” is not the be-all and end-all for describing good code. It’s just a nice substitute for the horribly vague, terribly subjective “clean”.
That said, in the book he covers correctness and understandability in nearly every paragraph. It's all the book is about really. It's called "clean" because it's concise and a catchy book title.
For example, the book presents a rule for class names:
> Classes and objects should have noun or noun phrase names like Customer, WikiPage, Account, and AddressParser. Avoid words like Manager, Processor, Data, or Info in the name of a class. A class name should not be a verb.
What a proclamation! We could connect this to correctness and understandability. But the book does not. You could say that it is harder to understand a class named “SomethingManager” because “manager” is vague, and more specific words are usually preferred. Instead, the book presents a rule, without explanation or example. Kind of like the Strunk & White book on style, and if you like Strunk & White, then we disagree on at least two books.
That’s my general complaint about the book. Too many proclamations, too much doctrine, not enough explanation or foundation.
What shall I call the unit of code orchestrating these download processes, if not ImageDownloadManager?
ImageDownloadManager manages image downloads. Why use a name that makes less sense?
I'd be happy to shred Clean Code, but keep your hands off my Strunk and White!
I disagree. Also, tastes vary and it fits mine. Thanks for recommending Style, though - it's very good and I fully get that it may be preferred by other writers. It also serves a slightly different purpose to Strunk & White, so the two can co-exist on the same writer's bookshelf.
You're right, the problem is vagueness, and that context is already set a few pages prior. It would be redundant to repeat the same reasoning.
I found your argument starting around 28:00 interesting. I’m not familiar with the specific tools you’re using and their idioms, so it’s possible that I’m missing some context here. As a general principle, I like to make it very clear where code is doing I/O and what is happening with any data involved. If this function receives data in one format, transforms that data into another format and finally sends that data to the database, then to me that seems like a useful separation of concerns and a clear representation of the overall behaviour. Maybe I wouldn’t choose the same name/structure as User.registration_changeset in your example, but the principle of hiding the implementation details of the data transformation seems helpful, for the same reason it’s helpful to see Repo.insert() instead of five lines of SQL at this level of the code.
There's a deeper problem here that has driven a lot of disputes over the years.
"Ease of understanding" is not a stable property of code. If you have two separate pieces of code that are easy to understand, and the only thing you do with them is combine them, your resulting one piece of code may also be easy to understand.
Or it might be next to impossible to understand.
That's not the reason to use enums instead of parameters for functions, rarely will you not be able to understand what the bool arg means in:
create_user(..., is_admin: bool)
The reason to use enums and for that matter structs is that as requirements evolve, inevitably you will need to extend the code base and at some point `is_admin` alone won't cut it, you'll need an is_moderator etc.
This leads to two things, one is function signature pollution and unnecessary extra validation code, eg. what happens if both is_admin and is_moderator are set?
What about the functions relying on the old signature? Perhaps you make separate versions of the functions, eg. create_admin_user and create_moderator_user and keep the old one with the flag, then you can keep backward compatibility...but at the cost of an api that makes people go insane when using it.
More likely you'd then go to an enum which leads backward incompatible changes, and likely a refactor, which in the event of a library can break dependent code and in all cases is a lot more work than just using an enum in the first place.
Try to write code for the future reader and writer of the codebase. An enum will allow readers to immediately understand that there is a [normal, admin] distinction and adding a moderator would be as simple as adding a [normal, moderator, admin] in there.
Then, assuming you've written your code in a proper manner, your IDE will tell you all the places where a moderator needs to be accounted for in the code base.
IDEs help with this of course, but it's not just the "2 options becomes 3 options" situation that recommends against them
Is this a username or a state?
create_user('ADMIN')
create_user(ADMIN)
create_user(User.ADMIN)This is what drives me nuts about seemingly simple rules like this: they let you feel like you can turn off your brain. You check all the boxes Clean Code tells you to and you feel like you're done. But you need to think systemically, and little simple maxims like "don't use bool flags" or "enums > bool flags" let engineers miss the forest for the trees over and over again.
there is nothing obvious about this, I think it's very objective what unreadable means (mostly it's complicated without a reason)
What if you have three people in the same code base who write "easy to understand" code for them, but inconsistent with each other?
Even if those three all understand each other while writing it, this will not continue as the team changes and people have to onboard.
As such, it isn't sufficient to have a linting standard: great codebases should have a consistent mental model. "Clean" code, within the context of Bob Martin "Clean", is one consistent mental model. I don't like all of it, but it gives one coherent top-to-bottom model.
The same applies to code. It is not 100% deterministic metric, but it is relatively easy to argue and have a consensus upon.
If you’re a reasonable person, yes. But when you’re not, all kinds of crazy patterns evolve.
E.g. a boss saying “I’m perfectly ok with functions that take more than 100 arguments.” (Compiler does not even support this.) and code being copy-pasted dozens of times being perfectly readable, but is a sink-hole when you refactor.
Clean Code (Martin’s book, and the movement in general) is my weapon when stubborn colleagues will not listen to reason. Sometimes they will listen to authority.
Just thinking out loud here, but isn't correctness(grammar and spelling) the only thing we all(mostly) agree on? For example, someone well versed with old English literature may consider Shakespeare easy to understand, but I certainly wouldn't. I think "speaks clearly, easy to understand" are just as subjective as our notions of clean/idiomatic/readable code.
What happens when half of your code uses functional patterns and the other half imperative/OO?
Completely agree. Bob Martin “Clean” has some really good recommendations, and some subjective advices. Normally the dev team can use this mental model as baseline and agree on which of the subjective advice to follow.
I just had an issue related to this recently, one of the senior software engineer in my team was previously a university professor with no software engineering experience. Every code review is an endless discussion, as he don’t agree with most of Martin “clean” code. So his code not only has several bad smells, but it feels like a completely different dialect. It forced us to have really basic discussions about code practices, even when to use comments (the professor likes to comment almost every line of code).
We should break out of the ide and visualize code more. I think then we would see the tangled mess we are creating. And then if we started talking about code that was cleanly visualized, we would truly have understandable code.
We need two-way sync for visualizations of all data structures and data flows. And then we need to see the actual data values inline as it flows through the system as we read the code.
Wallaby.js is a great leader in this space. I found it too hard to setup and too slow - but I’m convinced this applied to the entire stack is the future.
We draw diagrams on the whiteboard to explain every system but they are completely absent when we actually code.
It's a very under-appreciated feature, but I know what you mean.
Alongside NCrunch, Wallaby is one of my most valuable purchases. For those not familiar with the feature being referred to, as a continuous test runner one of the great benefits is that the IDE plugins show the values of anything (variables etc) in your code, live. I don't mean some kind of hover-for-intellisense, but at the end of each line you see all the values for all the variables all the time.
So in real-time, as you code, any tests covering the code you're changing are being run and you can see holistically how everything you're working on is changing as you type.
Basic test runners run continuously on the command line. Better ones run in the background of your IDE, possibly adding coverage markers etc. Wallaby goes one step further and actually decorates your code with real values live in the IDE as you work.
It's very good (though, yes, tricky to set up and a little slow).
Can’t stand being asked multiple times to change something depending on what order people review code.
I’ve learned to love auto linting for the sole reason that it instantly shuts down any discussion on styling.
"If a function is only called from a single place, consider inlining it.
If a function is called from multiple places, see if it is possible to arrange for the work to be done in a single place, perhaps with flags, and inline that.
If there are multiple versions of a function, consider making a single function with more, possibly defaulted, parameters.
If the work is close to purely functional, with few references to global state, try to make it completely functional.
Try to use const on both parameters and functions when the function really must be used in multiple places.
Minimize control flow complexity and “area under ifs”, favoring consistent execution paths and times over “optimally” avoiding unnecessary work."
http://number-none.com/blow/blog/programming/2014/09/26/carm...
A compiler should do this for you.
> If a function is called from multiple places, see if it is possible to arrange for the work to be done in a single place, perhaps with flags, and inline that.
This makes no sense to me.
> If there are multiple versions of a function, consider making a single function with more, possibly defaulted, parameters.
This can be useful, but only if it does not mess up code readability unless you are trying to squeeze your code into a cache.
> If the work is close to purely functional, with few references to global state, try to make it completely functional.
This makes very good sense, but it can be harder than it seems. One of the easiest ways (depending on how far down the call stack you are) you may just be able to pass the individual parts of that global state in as parameters.
> Try to use const on both parameters and functions when the function really must be used in multiple places.
Not all languages support this, but where they do this is good practice. In general: limiting scope and mutability is always an advantage.
> Minimize control flow complexity and “area under ifs”, favoring consistent execution paths and times over “optimally” avoiding unnecessary work.
Is also good advice.
In general you want to avoid nesting your ifs too deeply because at some point you lose track of what the local context is that got you there. Then it is usually better to break out a function and name it well so that that context is clear again. In general, naming things well is hard.
Point of inlining is to make it explicit that it is an ad hoc implementation for that location, so you don't have to be afraid of adding more stuff in it just to solve a local problem.
Unless it outputs source code, it can't.
So GP points out that, no, unless your compiler is outputting source code (therefore changing what you see as a programmer), having it inline the function does not accomplish the goal at all.
His later addendum is important not to omit, because this is really the key to more reliable code:
> The real enemy addressed by inlining is unexpected dependency and mutation of state, which functional programming solves more directly and completely. However, if you are going to make a lot of state changes, having them all happen inline does have advantages; you should be made constantly aware of the full horror of what you are doing. When it gets to be too much to take, figure out how to factor blocks out into pure functions (and don.t let them slide back into impurity!).
The main keyword is consider. Sometimes it's a good idea, and sometimes (often) it isn't.
but we assume that Martin doesn't literally mean that every function in our entire application must be four lines long or less.
Unfortunately I have worked (and fortunately, briefly!) with codebases like that --- not surprisingly, in Java. In addition to the complexity of whatever the code is doing, smashing things into tiny pieces also adds its own complexity. The fact that a short function is "easily understandable" on its own, which is what a lot of proponents of this dogma argue, is useless for understanding the functioning of the whole. The latter is far more important when debugging.
Function length is ultimately meaningless. I'd rather have a 5000-line function that reads top-to-bottom, than 1000 5-line functions if it means I don't have to jump around several-dozen-level-deep callstacks and try to keep track of 30+ character long identifiers to understand how the thing works.
The one part of Clean Code that saved my sanity was his choice of names and flow. That made it somewhat easier to navigate.
I have experiences with other code where it was so abstract, it took much longer to figure out.
I like to go by the rule: "write code for the average developer". I think finding that balance makes it easier to grok the code and maintain it.
Not easy to spot side effects if the 5 line function calls 999 other 5 line functions, which you have to do if you replace 1 function with 1000 functions. When people start to arbitrarily break up tightly coupled implementations into tiny functions you will get a much worse mess than if they just kept it as big as it was when they developed it.
Small functions are great, but forcing people to write small functions is not great. They are two different things.
In a programming context:
- If the business process you are trying to model clearly has 20 discrete steps is would be silly break them into 4 groups of 5 steps just to hit the ideal function size.
- Coming up with a good name for an abstraction in a moderately large program can be very tricky, but a poor name is hurting more than helping. Don't split it if you cannot think of a good name.
- If breaking out into a function requires passing in 10 variables then it may become harder to read than simply inlining it. You're probably not abstracting correctly in that case. Etcetera.
I've seen so many over-abstractions from junior programmers trying to be "clean" I wonder if these rules of thumb aren't hurting more than helping.
*) message handlers in raw Win32-apps come to mind
Over time they all got gradually broken down into smaller functions/methods.
(Disclaimer: I was not the original author of any of these.)
That said, a lot of these huge functions were basically for implementing defined step-by-step processes, and comments delineated the sections as well as loop and condition ends.
That is they should read top to bottom with minimal jumping around and information hiding.
(Of course not in all cases, YMMV, etc)
Only from there it becomes possible to have the broad view, reorganize and (re-)factorize the code again properly.
So if I had to choose between both, I'd take the 5000 lines function any time, since it makes my job easier.
What I think matters in the general case is the likely mutation rate of the code, and the familiarity of its design. Both of these are speculative, subjective factors, so right-sizing a function is basically a gut feeling. It can prove wrong in hindsight and others can disagree with your choice from the get-go. So it goes.
But a library function that won’t need much maintenance and implements a well-known pattern, style, or algorithm can safely be much longer than something that’s likely to see a lot of change (especially by other people) or that’s very unusual.
But we work with 1000 five lines functions all the time in high level languages.
All the stuff done on array/list/hash and the likes (map,fold/inject/reduce,sum,select,reject..) are five lines functions.
Why would you not want that for your own types?
Of course there are a lot of 5-line functions in that set, and also some 500-lines functions and also many functions that recurse or stack very deeply, and also some very shallow ones. They’re polished stones.
But function length isn’t a useful goal in itself and if it’s made to be, you’re deprioritizing the many other factors that matter.
I don't think that's the reason. The cultures of Java, C#, and now TS/JS definitely seem to worship abstraction far too much, and as a result you end up with what's classically known as "enterprise" code. I've seen the work of "low skilled devs" in other languages like PHP, VB, etc. and that leans far on the under-abstraction side; you're far more likely to find lots of copy-pasting and kiloline-long functions (if they even bother to write more than one), yet that code tends to be easier to work with in my experience because it's largely linear and not nested.
I still think it's just low skilled devs vs professional ones. You can make similar mistakes with many, many languages, it seems to me that Java went out of fashion, considered old.
I'm also working on a modern Symfony PHP codebase using popular 3rd party Symfony bundles. I've used Symfony for a decade but find the compiler passes and levels of abstractions (particularly when debugging 3rd party bundles) slow me down and make the code less understandable. Yesterday I spent half a day tracking down a bug which was the wrong setting in the config, but was obscured by too many layers of indirection.
I'd take the terrible but understandable codebase any day as I know I can debug and improve it more easily.
I guess we both may have good anecdotal examples :)
Unfortunately true. C# has been around long enough that some of the more 'mature' developers I've worked with still treat the book as gospel. Trying to find the actual code that does actual work can be tricky. That's started to change in recent years fortunately - especially with newer developers joining thanks to the increasing popularity of Core.
As to the discussion: my basic rule of thumb is that single responsibility should be applied to every level of the stack, whether that be a single microservice, a single controller, a single function, or even a single property. Provided you follow that, many of the discussions vanish.
For instance, how big should my functions be? Big enough to do one thing. Any bigger and they are too big. Any smaller and they are too small. Regardless of lines of code.
So it narrows down to a simple decision - in the context of the code I'm writing, what is the one responsibility of this function? Following that practice it rarely ends up as a one-liner as it is hard (not impossible!) to encapsulate a complete piece of work in one line. It also rarely ends up more than a screenful as that usually means it's doing more than one thing.
The important point is to switch the question away from "How big should it be?" and instead consider "What is the sole thing it is responsible for?" [1]. Then write code accordingly. After all, we know from the bad old days of being paid per line of code that 'lines of code' is a useless metric.
---
[1] I'm aware that defining the responsibilities too tightly leads to fragmented code and a multitude of functions/abstractions. I'm also aware that defining them too loosely leads to huge functions and monolithic code flows. I'm not offering an answer, just saying we need to rephrase the question.
Deeply nested code is read only, unless the problem is nicely modelled as recursive in some way.
It’s when your data items have children, which can have children, which can have children...
Though, I'd agree that is quite different when someone puts in a linter that requires 5 line methods and scatters the flow of logic.
IMHO, "imperative shell with functional core" (which implies consistent levels of abstractions) is a follow up the book could really use.
To another extent, I think small and controversial rules of thumb like "keep functions short" can easily be taken out of context. A refactoring I often see that can be done when methods are poorly broken up is class variables can be converted into local variables once some of the methods are inlined.
The point of the small function is so that a developer can keep track of fewer moving parts in their head while reading. If the shattering into functions causes the class to have 30 class variables in order to support that, then it's very much a case of following the wrong heuristic. IIRC, clean code holds a highest priority on the developer only needing to keep track of 3-5 things at a given time (and pretty much everything else is in service of that goal)
That’s unfortunate because it’s my specialty and what gives me job satisfaction.
I love fixing things. I actually enjoy working on a crappy codebase that has made the company money but is now too hard to maintain/extend and needs cleaning. Adding tests, refactoring, extracting functionality to discrete functions, figuring out what the black box actually does, etc. This is what I’ve specialized in.
However, it seems to me that companies don’t actually value that. They all say they do of course, while actually being afraid of doing this because it takes more time and money. Even if they’re mature enough that survival isn’t an immediate concern anymore, there is time to clean things up, and the mess is actually slowing them down through downtime, bugs, and not being able to ship relatively trivial features/updates in less than weeks.
I also suspect that not focusing on clean code is a strategy many managers have because they can show velocity to their higher ups and get promoted before it all blows up and they’re held responsible.
So what do you all think? Is clean code really actually valuable in the eyes of organizations or will they always take the quicker and dirtier option given the choice? Will I ever find work selling code cleaning (even to companies that ask for it) or should I “rebrand” on fast and cheap code at the expense of quality?
But it is known that a quality foundation enables everything in the business, reduces waste, churn, and increases profits.
Yet when it comes down to actually doing it, nobody cares. Fast and cheap always wins over quality.
That’s not necessarily a problem overall, but it is for me because I derive no satisfaction from shipping low quality code and the constant firefighting that results.
This is a struggle because it’s the vast majority of the demand for software, which makes me want to quit the industry altogether even though I love programming and improving “legacy” codebase. But there seem to be no actual demand for this skill despite the appearances.
To reuse your analogy, I’m talking about a restaurant who has a mess of an installation, several panels and breakers, not all up to code, and the electricity frequently shuts off taking hours to figure what happened and how to restore it. It’s also a mild fire hazard and there have been a few close calls that could have burned the place down.
The son in law, a hobbyist electrician, did the installation and extended it for free while the business was starting up and growing. He didn’t do it right but it works and got the restaurant so far.
Now the restaurant is very popular but the constant blackouts are driving people away and hurting profits. The mild fire hazard and not following code irks the authorities and insurance companies and they’re threatening closure. It needs an extra stove to keep up with customer demand but no one can figure out how to hook one up to the existing rats nest, let alone do it safely.
The owner knows this is a problem and is looking for a proper electrician to fix the mess.
In real life, I’d expect the business owner to agree with the electrician on a plan so that either the retaurant stays open (maybe at a lower capacity) so that the tidying up can happen gradually, or close down for renovations for a while so the whole thing can be overhauled quicker.
But what happens in our industry and in my experience is that instead the restuarant owner asks the electrician to tighten a screw or two here and there so that this power socket isn’t as wobbly anymore but then demands even more additions to the janky system and demands they be done as fast and cheap as possible as this is now the top and only priority.
Nothing really improves but the owner (at least for a while) can hide it from the authorities and insurance company because he has a quote and a specialist working on the system. Then the owner can blame the electrician because “he wasn’t able to balance fixing up the installation while extending it, so we’ll fire him and look for someone actually good this time”. Rinse and repeat ad nauseam.
That is my experience too with most places - they say that they support clean, well tested and maintainable code and then turn around and ask things to be delivered in unreasonable time resulting in quick and dirty code.
> I also suspect that not focusing on clean code is a strategy many managers have because they can show velocity to their higher ups and get promoted before it all blows up and they’re held responsible.
Indeed - furthermore, because the code lacks quality, it requires more effort to manage and (intentionally or not) helps them to demand headcount which requires more managers which results in them building hierarchies, moving up and having their fiefdom. It is a smart approach too in a perverse sense: how will you get to a position managing 100 people if you only delivered with 5 people due to your efficiency? You'll be labeled as "lacks experience managing large orgs".
I can’t stand self inflicted toil and the stress from constant firefighting which is invariably the result of these short term policies. It makes me want to quit programming altogether and work in something totally unrelated even though I love programming. Just not the way employers want it.
I don’t want to be part of the problem either by becoming one such manager so that others will have to pay the cost of my benefit.
What’s left? Opt out, live on shoestring budget for the rest of your life, and hope it works out?
The one whose designer said “ They’re not capable of understanding a brilliant language“
So find places and maybe start at industries that consider their code an asset or profit center.
It’s ultimately just a valuation perspective, but understand to a business everything has a market context or business case. It’s can be infuriating, but better to know the system than blindly suffer through it.
Clean code can bring tangible value, but big rewrites taken on for that goal can often not. I personally try to be more pragmatic--what is valuable depends a lot on context and the point in life of a particular project+team+organization.
Sometimes the most valuable thing is to ship a messy code that works to get the ball rolling or prove viability of an approach. Other times it's to make sure what you deploy is bullet proof to avoid liability or expensive downtime. The value of clean code will be reflected by your team and organization's needs at that point in time.
For sure, and I only target companies or teams that are mature, struggle to move forward because code quality grinds things down to a halt, and that express the desire for improvement there.
However, there are very few companies that 1. Even have the awareness to realize this is where they’re at, and 2. Actually mean it. I’ve been passed over many times in favour of someone else who ships code quickly and cheaply by lowering quality. Every place I’ve ever worked at, quality is the least concern in relation to the others.
Now for a startup that has limited runway and has to find product market fit for example then it’s totally different. Focus rightly is on shipping stuff at the expense of quality because survival is on the line. In a few years, once this company has made it, they’ll look for someone to clean their codebase up.
My broader question though is whether I should keep branding myself as a “code cleaner”. Despite a (minority) of companies advertising positions for that skill, my experience has been that the vast majority simply don’t care. And those that do, don’t actually care all that much. It’s a struggle though because I get no satisfaction from shipping low quality code and eventually end up quitting out of boredom or frustration. I’m now at a point where I’m considering doing something entirely different from programming because I can’t derive any job satisfaction from writing low quality code and the resulting constant firefighting that results from it.
I’ve never come across such an organization though. There are a handful that I think are in this spot where quality has mattered since day one but they’re so popular that I don’t stand a chance to even get noticed when applying in a sea of thousands of applicants. They also don’t hire very often.
And they’re very hard to find because what do you even search for? The ones I know, I found empirically through word of mouth, reputation, or just plain randomness by stumbling upon.
I am thankful that people like you exist, but after having taken on that role out of necessity myself, I've mostly been left disliking the experience.
Working withing under-documented and under-tested "legacy" codebases, especially the kind where the developers got clever with design patterns, both putting them in when they make sense as well as when they didn't. Those codebases are hard to navigate and hard to refactor (outside of fully automatic renaming/extracting interfaces etc.) and even harder to change - in many cases because you're not even aware of the design assumptions or aspects of the architecture that were made by someone who is now long gone.
For example, I worked on a system where users could submit corrections to data and those could either be accepted or removed. There was a CorrectionFormService, that also was related to CorrectionEntryService, but both of those were abstract and had corresponding CorrectionFooFormService and CorrectionFooEntryService instances, as well as an additional CorrectionFooService. In the database, there also were foos and foos_corrections tables, the latter of which was related to correction_forms, sometimes with additional related tables. The problem was that the logic didn't actually fit such neat structure, so depending on whether you're working with Foo, Bar or Baz, more and more of the methods had to be overriden, as well as new ones added, none of which was actually documented. In most cases you were supposed to have the original_id column point at the foos (or whatever) table id that had the actual data, except when for some reason original_id was the same as id and instead you had something like object_id store that information. And on top of that, there were database views which were used for querying the data, where there were additional rules for the id, original_id and object_id column values, with about 10 prior Jira/Redmine issues related to how this data should work. Not only that, but there were also requirements for accepting some of the data recursively (since parent_id was needed for some of the data structures), but not in all of the cases, only when some other enum column had a particular value in a related table.
Long story short, the more you looked into it, the more details spilled out, to the point where you could not keep a full mental picture of it in mind. Some of the implementation was okay, some of it was ridden with iteration overhead and accidental complexity. Contrast getting to write new code and getting things done in hours, versus spending days if not weeks (across multiple developers, actually) working to get things done within this pre-existing setup. Maintenance work will typically take longer than developing new features and, in my personal experience, will be more mentally draining.
Rewriting is tricky. It’s sometimes necessary (outdated and unmaintained language, obscure tech you can’t find people for, or sheer tech bankruptcy) but it can also not solve anything. As you implement the new version, you rediscover all the arcane business rules, edge cases, and sheer craziness that you didn’t know about and the rewrite ends up either lacking these or becomes The Mess v2 because you had to bolt all this weirdness on after the fact making the new codebase suck in a different way but overall as problematic as the one it replaced.
It will also take much longer than estimated for the same reasons.
I’m not super keen on rewrites in most cases.
Sometimes I wish we could just look at an implementation that's meant to serve a business process and go: "Listen, we gave it a shot, but the technology and developers we have available cannot provide a satisfactory implementation for this, without making the entire thing a liability. Can we simplify the domain instead?"
I've actually tried this in the past (in a more mild form) and it has actually worked - sometimes getting a paragraph or two of changes approved in a 50 page spec can save you weeks of work ahead of time, which you'd otherwise spend because someone didn't realize which parts of the spec are technically unfeasible.
Sometimes it's actually easy to reason about, such as when you're doing a rewrite from AngularJS or something else that's deprecated to something more modern, and can suggest a few simplifications to "prioritize quicker iteration, shipping core features quickly and simplified UX for less friction", which might mean simpler components.
Or you might find yourself in an inflexible domain, having to replicate "the old thing" close to 1:1 which will take way more time than either writing or maintaining it would. There, rewrites don't make that much sense. At that point, if you need more modern elements (runtimes, libraries, frameworks), I'm not even sure what you could feasibly do, aside from setting up a new service and rewriting paths for particular new API endpoints to the less rotten codebase, but that has challenges of its own and can get out of hand.
I can see this working in more mature and healthier orgs, but they’re a minority. As cynical as it sounds, most orgs are dysfunctional meat grinders where you’d get attacked for not having the skills to pull it off, in my experience.
Nobody brings this up for that reason and the madness continues unabated, ensuring the project becomes a slog over the medium/long term with the expectation that most will have moved on before it gets there.
This is also how we run our societies, leaving problems for later so that the next guy/president/generation has to deal with it at the point where it’s impossible to ignore anymore. Instead of much earlier when it requires much less effort and is reversible.
You could start execution right away! Every bit of information is readily available, sure, the numbers in those emails might change in the process but you can just document those changes on additional napkins.
But there is a stage 2 to the plan that needs to happen in 3 to 6 years. By then there will be tens of thousands of relevant emails, hundreds of napkins, you cant find the original photos and you have so much related information in your head that that important thought is buried much like the email... I'm sure I have a folder someplace on this computer.... where is the chat log?
You made promotion so stage 2 is left to the new hire. They had a wonderful resume but for some reason it takes him forever to progress. They wont argue it would have been nice if you wrote down what stage 2 involved years ago. In stead they ask for 20 more people to organize the data.
So while not 100% of my job is refactoring, a large portion is. And sometimes I convince them it’s time to rewrite one entire section or another, so a couple of sprints at a time might be dedicated to just that.
I guess I’ve gotten lucky, probably a combination of that and being outspoken about what needs to be fixed.
There's many sides to this.
Even Boeing doesn't value clean code (as shown by the 737 MAX disaster where 9$/h coders were hired in India). So you can imagine how much a local non-tech company values clean code.
There's also that a lot of these companies simply... couldn't recognize clean code even if they saw it! Since they aren't competitive with top players, the caliber of programmers they attract is nowhere near the level of engineers at real tech companies. Unless these companies "luck out" with an extremely high caliber hire, they won't really know there's a better way of doing things [0]. Think places where source control is still seen as too complicated or not needed.
[0] https://www.hanselman.com/blog/dark-matter-developers-the-un...
[0] https://www.businessinsider.com/boeing-outsourced-737-max-re...
[1] https://www.bloomberg.com/news/articles/2019-06-28/boeing-s-...
Still my word holds good . Boeing management didn’t give crap about engineers opinion be it 30$ per hour or 5$ per hour.
What we know was outsourced is "flight test software" which sounds a lot like something that should have caught the 737 MAX failure...
I'm not sure how it got its status at the beginning, but I think it retains it through sheer scale - it's a gigantic book for what it actually contains. It batters you with poorly connected ideas over and over and over until you can't tell right from wrong, and in the end you're just agreeing with whatever because doing otherwise gets you nowhere and nothing but pain as you try to read more. It's like a cult brainwashing ritual.
But now in my career I’ve seen awfully unnecessarily complex code in the name of the SOLID principles and others like DRY. Other times completely misunderstanding what the principles stand for and applying them in hand wavy ways.
This is a personal stretch, but even the marketing behind the principles is a bit of a red flag for me (Clean Code, SOLID, UNCLE BOB????). To me it sounds like someone made a career out of this.
I wish we had a better book to recommend to newcomers.
It isn't so concerned with all of the details about what exact decisions you should make ("how many lines should my function have?" etc), but rather the high-level design choices that go into those decisions. A lot of the book is spent on the philosophy of interfaces, which is the author's way of describing the boundaries between a piece of code and its caller.
It's written by John Ousterhout, of Tcl fame (among many other things) based on his own experience, but also his attempts to teach software engineering to students, and the techniques that worked well for those students in practical situations, so I think it's fairly well grounded in actual advice.
It's also recommended in this article:
"Update, 2020-12-19 After suggestions from comments below, I read A Philosophy of Software Design (2018) by John Ousterhout and found it to be a much more positive experience. I would be happy to recommend it over Clean Code".
> Consider this book a description of the Object Mentor School of Clean Code. The techniques and teachings within are the way that we practice our art. We are willing to claim that if you follow these teachings, you will enjoy the benefits that we have enjoyed, and you will learn to write code that is clean and professional. But don’t make the mistake of thinking that we are somehow “right” in any absolute sense. There are other schools and other masters that have just as much claim to professionalism as we. It would behoove you to learn from them as well.
> Indeed, many of the recommendations in this book are controversial. You will probably not agree with all of them. You might violently disagree with some of them. That’s fine. We can’t claim final authority. On the other hand, the recommendations in this book are things that we have thought long and hard about. We have learned them through decades of experience and repeated trial and error. So whether you agree or disagree, it would be a shame if you did not see, and respect, our point of view.
Generally dogmatic people don't say, in short, "We could be wrong, we don't think we are, but go see what other people have to say, too.".
> the book was inconsistent and dogmatic.
How do you square that with:
> The claim is not that the book is dogmatic
You are claiming they didn't write what they wrote.
“Code should be readable” is a higher level goal that is inevitably subjective, so it is harder to enforce than for instance, DRY.
A disclaimer doesn't change whether something is done or not. And it's a rather small fig leaf compared to the rest of the book.
No book, no philosophy, no technique, no programming language, no ChatGPT can ever remove the need for the programmer to think for themselves and determine their own approaches to programming and which approaches are appropriate for which programs.
[0] I keep using they and their, there were multiple authors for the book. Several chapters were written by people other than Martin.
I imagine the strength of their arguments would be approximately related to the strength of said arguments merits / demerits. You don't have to present an unyielding argument if your goal is to educate your reader and help them to reach an informed position.
He's saying he expected more, coming from a different background with a culture of rigor.
https://pomasearch.com/blog/why-is-this-site-named-poma-and-...
"And, when I was listening to them, they all sounded to me like, to me, extremely bureaucratic programming that came from the mind of somebody that has not written a lot of code, frankly."
...What just happened? What was flicking the switch for? Was tapping the empty mug part of the procedure? Where did the coffee come from?
That's what this code is like."
This is such a good metaphor
[function that restates its implementation]
and
[function that restates its implementation]
The article's main beef is that Clean Code sets standards that it itself does not meet. The author makes that point through the above examples and many others. The sheer number of examples suggests that this is a regular pattern in the book.
The reason seems simple enough: it's really easy to give general advice about writing software. But it's quite another thing to put that advice into practice as the thing you're working on turns to goo, which is exactly what appears to have happened with Martin's model project, FitNesse.
It's probably time to stop recommending Clean Code - https://news.ycombinator.com/item?id=29203295 - Nov 2021 (88 comments)
It's probably time to stop recommending Clean Code (2020) - https://news.ycombinator.com/item?id=27276706 - May 2021 (658 comments)
It's probably time to stop recommending Clean Code - https://news.ycombinator.com/item?id=23671022 - June 2020 (8 comments)
Programming rules are important - they make you think before you break them. Just don't turn rules into dogma - otherwise your devs will be more concerned with following the rules than solving the actual business problems. And you don't want that.
Rules should help you along, perhaps set a framework for your thinking. But they never should limit you in achieving your goal. When establishing a rule you should also specify what you want to achieve by it, how you'll measure its effects and under which conditions it should be removed.
Rigid rule enforcement has a strong danger of shifting the priorities of the developers to the detriment of your business.
Each time I see the same discussion on HN about this book, I'm always wondering why I see so many people going in either direction : not following the advice of the book at all, or following it too religiously.
For me, the philosophy of the books was always about "having a set of guidance on how to improve your code, IF YOU NEED IT", and never about a strict set of rules that were mandatory to follow in order to have "clean code".
The fact that the book gives strong statements about what clean code is, such as "a function should be only one line" was always an exaggeration for me, albeit a useful one to actually makes the reader think more deeply about its function length, but never about forcing you to split your 1000 lines functions into 100 functions of 10 lines, if you don't need it.
A craftsman is an expert in his field who applies his knowledge and techniques judiciously, not religiously or automatically.
While the heart of Martin's teachings are about expressivity and semantics, the praxis is much more about recipes than about what matters to me as a professional, which is:
1. Well-definedness of the computation being done (in a mathematical sense of the word),
2. Engineering, that is establishing of a connection between human narratives about what the SW should do with the program's structure.
Overall, it seemed to me that Martin is first and foremost trying to sell to sell a certain paradigm of competency to corporate cookie-cutter-culture organizations.
My issues with this paradigm of competency are that:
1. Doing it properly requires a massive investment, which does not make business sense.
2. As is often the case, this paradigm makes it easy to feign competence without actually being competent, which is damaging to organizational trust.
We shouldn't be surprised that it's popular, or that it's highly associated with Java (and certain other languages today).
I liked its notion of symptoms of complex code.
I liked its framing of complexity as related to dependencies involved in calling some function. -- If a function has more parameters than it really needs (too many dependencies), or a function has fewer parameters than it actually needs, then it's more complicated to work with than it needs to be (its actual dependencies are obscure). -- I liked its emphasis on "interface" is "what you need to know to use the code", as opposed to implementation details.
I liked the suggestion of "writing documentation before the implementation" as a way of coming up with a clean interface; although I found it bizarre that this logic didn't carry across to "write some tests before the implementation".
What matters is understanding the "general concept/ideas" and apply them "as appropriate".
Most important over obsessing about specific rules is nearly never a good idea, but to some degree that is what is needed to write a book like that to illustrate the idea. And this is also where Clean Code fails, it's often too specific in exactly how to do certain things. But that is also what made it so successful because it makes it accessible.
Today Clean Code and some other such books are still a grate source to compare your experience/knowledge against in a critical way to find additional insights.
Through if you want a book which you can blindly follow or you don't have the experience to judge code style recommendations its probably best to keep the hands of it.
If there's one thing I slightly disagree with, it's that I would put Code Performance below Test Performance, but that's because my personal experience ([1]) has been that code performance affects test performance more than anything else.
But still, this is an excellent model, and I'm bookmarking it. Thanks!
[1]: https://gavinhoward.com/2019/08/why-perfect-software-is-near...
And, code performance is, as you say, part of test performance. If the tests take too long, perhaps the code needs to be improved. OTOH, I have got a few test suites that run for 30 minutes or more, just because the search space is so big. But that's code that only needs to be tested once.
Yes. I mentioned this is in the last section. When test-performance is alright, typically you don't need to optimize code anymore.
For me, optimizations in the "code performance" category are for example trading off a generalist API for a more complicated tweaked version that reaches into details and enables caching. The kinds of optimizations game developers do where they make the code less general and pretty, but more performant.
> OTOH, I have got a few test suites that run for 30 minutes or more, just because the search space is so big. But that's code that only needs to be tested once.
What are these suites testing?
One is testing all permutations of actions on some observability thingy: does everyone get the updates they requested in the correct order, basically, but suppose you have 3 "clients" that can connect and disconnect at arbitrary moments, and we're testing a single insert-like operation on the initial empty data, there are already dozens of combinations.
Another one is some operation on two arbitrary JSON objects and an inverse, and I wanted to make sure that it works for things that look like normal looking objects, small and large, and for "random" objects. Fuzzing with hierarchical data. This code is in JS because it has to run in the browser, so it is not super fast.
> This code is in JS because it has to run in the browser, so it is not super fast.
Try profiling heap allocations in Chrome Debugger. In my experience especially array-allocation can slow down JS-code a lot.
It's hard to imagine anyone going this far down the rabbit hole of strange code organization when they are facing serious challenges like real-time demands, high concurrency, reliability, complex algorithms, big data, embedded systems, etc.
Isn’t this by far the bulk of code businesses produce and need though? Very few businesses actually have the scale or product that requires more than a glorified CRUD with arcane business rules slapped on top.
Parent comment implied the book isn’t relevant because it only applies to CRUD apps and I argue that they’re the vast majority of code produced so while the book isn’t relevant to 100% of codebases, it is useful advice in the majority of cases nevertheless.
Edge cases are gonna be edgecases and will require tailored advice.
Don’t have to spend too much time bikeshedding. Experienced enough to have some foresight and pragmatic enough to know where to draw the line.
Should you take everything it says as gospel? No. Did reading it in the beginning of my career make me a better developer? Yes.
Its the same as with every other practice. Do I practice TDD? No. Did trying it out for some time learn me things I still apply to code I write 10 years later? Yes.
Ideally folks notice discrepancies between their experiences and the things it recommends and find their taste and judgement that way, though it doesn't always work out.
So like, maybe the fact that some of the advice is clearly dreadful if you try it could be a useful wedge against the kind of cult thinking so pervasive in software. I've seen considerably more grief from people treating his SOLID stuff like a bible that clean code. YMMV.
A lot of people have no idea how to write clean code and those parts of codebases and those people should be avoided as much as possible. I'm not trying to hate, but wow some devs have no shame.
It's code written in the typically over engineered OOP-heavy Java style. Think lots of "patterns", massive amounts of inheritance, interfaces and factories everywhere.
I made the decision of abandoning any clean-code-ish practices within my teams long ago.
I still demand the code to be structured sensibly, be clear, well named and documented.
Let's not add LOC if it's not helpful. I finally picked up Typescript to strengthen my Javascript code, and I'm a huge fan now, but a lot of the added features aren't always helpful whether because of project size or complexity. And the typeahead -> add code features on IDEs add a lot of bloat like yeah interfaces on _everything_.
Though it is an ill-defined term clean (clear, readable, reasonable, understandable) code is important in the sense that accidental complexity should be minimized and encapsulated and necessary complexity should be understandable.
Everything else can and should be constantly re-evaluated.
I read that book when I was young, I followed some advices, some I didn't, then I made mine ideas.
Of course reading others books is also very helpful to contextualise Clean Code.
What I really, really recommend is NOT to read The Clean Coder book by same Rob Martin, it's one of the few I have been unable to even finish, it has been unbearable to me.