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)
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 Commission list, 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 of calculateExtraCommissions. 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.
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.
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.
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.
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.
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.
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.
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.
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.
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!
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.
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?
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.
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.
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.
@dandi8@JackbyDev Most of the criticism in the article talks about side-effects using a far stricter (and imo more useful) definition than Martin did.
I tend to agree, and would avoid both side-effects and writing code like Martin. However this book targets the mainstream, and afaik the mainstream hasn’t yet accepted the new definition of side-effect.
Martin has since embraced FP more than the mainstream. So he’s somehow both ahead of and behind the curve.
This is a good point. A perfect litmus test for this is whether people consider logging a side effect. With the strict, functional definition it is. With the loose, practical definition it is not.
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.
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.
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.
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:
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:
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.
You’re making assumptions about the control flow in a hypothetical piece of code…
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.
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.
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.
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.
Because there aren’t 6 interesting levels of abstraction. It’s like talking to a child:
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!
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:
//or#would have made the code just as readable.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?
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.
@dandi8 @JackbyDev Most of the criticism in the article talks about side-effects using a far stricter (and imo more useful) definition than Martin did.
I tend to agree, and would avoid both side-effects and writing code like Martin. However this book targets the mainstream, and afaik the mainstream hasn’t yet accepted the new definition of side-effect.
Martin has since embraced FP more than the mainstream. So he’s somehow both ahead of and behind the curve.
Any examples of the claim that he’s embraced FP more?
Last I saw, he was making wild, baseless assertions about FP concepts like monoids and monads on Twitter.
@expr this is from 10 years ago https://youtu.be/7Zlp9rKHGD4
This is a good point. A perfect litmus test for this is whether people consider logging a side effect. With the strict, functional definition it is. With the loose, practical definition it is not.