Clean Code vs. A Philosophy Of Software Design

I cringe thinking about PR comments I left early in my career.

"akshually this should try to follow more SOLID principles"

But, coming from a formal engineering background, I thought this is what it meant to be a professional software engineer. Little did I know these "principles" were just the musings of a consultant lol. Turns out most folks have good intentions and want a standardized way to write code, but for some reason it always results in code that looks like the Enterprise FizzBuzz meme repo.

    > It still blows my mind how dogmatic some people can be about things like this. I don't understand why anyone takes these things as gospel.

IMO, this is one of the key differences between the two books. CC has a vibe of hard and fast opinion-based rules that you must obey, whereas APoSD feels more like empirically-derived principles or guidelines.

I think it stems from fundamental misunderstandings about what it is one is actually trying to do when writing code.

Coding is about building a computable model of some facet of existence, usually for some business. When it comes to model building, comprehension and communication are paramount. Performance and other considerations are also important but these are arguably accidental features of machines and, in an ideal world, would not actually affect our model.

Similarly, in an ideal world, we wouldn't even need programming languages. We'd be able to devise and explain computational systems in some kind of perfect abstract language and not need to worry about their realization as programs.

I think a lot of these blanket philosophies confuse people by not emphasizing the higher level aspects of the activity enough. Instead people get hung up on particular patterns in particular paradigms/languages and forget that the real goal is to build a system that is comprehensible to the community of maintainers that need to work with it.

Yes, Uncle Bob is certainly capable of being pedantic. A friend of mine, a Smalltalk Consultant, partnered with him for a while. "With Uncle Bob, it's his way or the highway."

His clean code work is certainly pretty dogmatic. As I recall, he says that Java is not object oriented.

But if my memory serves me correctly, his book about C++ (Designing Object-Oriented C++ Applications Using the Booch Method) has some excellent parts. His description of the difference between a class and an instance is one of the better ones.

Then there is the famous sudouko puzzle incident, in which a student trying test-driven development can't get the solution. It is a very instructive incident which illustrates the TDD is unlikely to help you solve problems that are beyond incremental changes. Peter Norvig's solution makes that very clear. Uncle Bob does not seem to realize that.

> Who else has had to deal with idiots who froth at the mouth when you exceed an 80 line character margin?

But I admit in my youth, I was pretty dogmatic about languages and development practices, so I've been that guy.

To restate something I've said here last month:

I'm fond of saying that anything that doesn't survive the compilation process is not design but code organization. Design would be: which data structures to use (list, map, array etc.), which data to keep in memory, which data to load/save and when, which algorithms to use, how to handle concurrency etc. Keeping the code organized is useful and is a part of basic hygiene, but it's far from the defining characteristic of the craft.

Remember when most people give presentations about a technology, they’re in the honeymoon stage

Professionals in other industries don't "just" write books. In a sense that usually the field has several acclaimed authors and they put some solid work into ensuring their books make sense. While there are disagreements in other fields, or some nonsense conventions, the conventional wisdom is usually at least good enough to make you a good professional.

In programming it's the Wild West. Many claims are made based on nothing at all. It's very rare to see any kind of sensible research when it comes to the science part of CS. But following rules makes life easier. Even if rules are bad. That's kind of why conservatism exists as a political idea.

> Always keep in mind that sometimes the only difference between yourself and the person writing the book/blog/article is that they actually wrote it. And that their opinions were written down don't make them fact. Apply your own mind and experience.

But that difference is actually huge. I think you are downplaying the value of the writing process. Assuming that writer is acting in good faith and truly tries to provide the best possible information.

But when you start writing, you start noticing that this idea might not be that good after all. Maybe I need to read more about this? Did you note everything? This idea conflicts with this other topic than I just wrote? What is correct? And the list goes on. When you structure all your thoughts as written text, it is easier to detect all conflicting ideas and mistakes. Not all writers are that good, but you should understand what I mean.

This is just how junior and intermediate devs behave. It’s like a goth phase or something.

It goes along with being into BJJ, chess, vim, keto, linters, and “the dominance hierarchy”.

It’s annoying, but most everyone went through it. If you didn’t know better, how could they?

> Who else has had to deal with idiots who froth at the mouth when you exceed an 80 line character margin?

Not once in my 11 year career. But almost every codebase I've worked on has had debilitating maintainability issues because the only principle other engineers seemed to follow was DRY, at the sacrifice of every principle in SOLID.

Because its easy to be dogmatic, you don't need to think, consider the consequences or drawbacks, you just follow whatever the Supreme Leader told you to do.

Its incredibly simple to just follow whatever someone is telling you to do, sometimes I wish I could live like this so I didn't have to fight with the people that do all the time.

On my Macbook Pro M2, having a browser window on one half of the screen, and my IDE on the other, with a file tree viewer pane and another pane for my LLM tools, a terminal pane at the bottom... I've never been more pressed for real estate for my actual code editing pane. Even 80 chars has me scrolling horizontally. Secondary monitors help but not when you frequently work away from your desk.

>> Always keep in mind that sometimes the only difference between yourself and the person writing the book/blog/article is that they actually wrote it.

Well said!

The worst engineer I worked with was one who believed if he read it in a book, that opinion trumped anything else. Once he got so flustered he started yelling “come back to the discussion when you’ve read 13 books on this topic like me!” And it was something super mundane like how to organize config files or something.

Made every engineering planning session a pain in the ass.

For many C#, Java and C++ engineers Uncle Bob is their savior and GoF are the apostles.

Everything should follow SOLID and clean principles and be implemented using design patterns.

FWIW (not a lot), I do believe in a lot of these principles.

For example, even with widescreen monitors, it is still useful to limit line length. Why? Because many people will have multiple source files side-by-side on one of those widescreen monitors, at which point it makes sense for them to not run on indefinitely.

And of course, that is just a guideline, one that I break regularly. However, if it's a method with many args, I'll break the args onto their own lines.

However, the overriding concern is that an organisation works to code towards a common style, whatever that may be, so that unfamiliar code is predictable and understandable.

> idiots who froth at the mouth

That seems like an unnecessarily harsh way to refer to people.

> It still blows my mind how dogmatic some people can be about things like this. I don't understand why anyone takes these things as gospel.

I love reading books for different perspectives.

However, I’ve come to despise people who read books and then try to lord their book knowledge over others. These are the people who think that they have the upper hand in every situation because they read some books. They almost always assume you haven’t read them. If you point out that you have also read them, they switch the subject to another set of books they read because they don’t like when someone tries to undermine their book knowledge superiority.

It’s even worse when the person reads books outside of their domain and tries to import that book knowledge into the workplace. The absolute worst manager I had was a guy who read a lot of pop-psychology books and then tried to psychoanalyze each of us according to those books.

> Who else has had to deal with idiots who froth at the mouth when you exceed an 80 line character margin?

Honestly, no better indication of a very mediocre developer

The place I used to work at had a "architect" who would for any question to a decision he made would refer to whatever it was as a "best practice."

Was often quite wrong and always infuriating.

Well I mean they wrote books about it and one guy had the audacity to call his opinion a “philosophy” even though it’s just an arbitrary opinion.

Most of software is about assigning big words and over complicated nomenclature to concepts and these things masquerade as things with deeper meaning when in reality it’s just some made up opinion.

Software design is an art. It is not engineering and it is not science. That’s why there’s so much made up bullshit. The irony is we use “art” to solve engineering problems in programming. It’s like ok we don’t actually know the most optimal way to program a solution here so we make up bs patterns and philosophies. But then let’s give this bs pattern some crazy over complicated name like Scientology or inversion of control and now everyone thinks it’s a formal and legitimate scientific concept.

Well cats out of the bag for Scientology. Not yet for a lot of the bs in software. A “philosophy” is the biggest utter bullshit word for this stuff I’ve ever seen.

Square people are never going to agree with cool people. You can be cool and code some monstruosity or you can be square and say "we have to rebuild this entire project from scratch" everytime you see a long method.

> The success is only the result of a wave of junior devs searching for some sort of guidance, something that there is a never-ending need for.

The issue is that, some never grown out of it. I interviewed with companies where they give the book to any new intern/junior. Then, during the hiring process, they don't even ask if you read it, they straight up ask questions about your knowledge of it. Like "What does Uncle Bob says about X in his book Clean Code?". And they constantly refers to it. Some people go as far as quoting it in PR.

The worst part being that once they leave their company, since they don't know anything else, they'll apply the same stuff elsewhere & convert their new company to it.

(English tip: advice isn't a countable noun, so you don't pluralise it)

I agree entirely. My encounters with Uncle Bob were as a junior developer receiving advice [no "s"] from other junior developers.

And yes, I too find it suspicious how many mavens of the "Agile era" never really managed to ship anything.

It is very instructional to read the source code to FitNesse framework.

https://github.com/unclebob/fitnesse

You can see how all his ideas come together into a ball of hundreds of almost empty classes, and gems such as "catch Throwable".

A Philosophy of Software Design on the other hand is concise, excellent, and based on decades of teaching experience.

Clean code, design patterns etc. were also picked up by teachers, professors and course instructors.

I think these paradigms and patterns often operate on the wrong layer of abstraction, while mostly ignoring the things that matter the most, like efficiency, error handling and debugging.

But getting good at these things requires a lot more blood, sweat and tears, so there's no easily teachable recipe for that.

> The only way around that would be with stupid method names

Yep. Method names make terrible comments. No spaces, hard to visually parse, and that's before acronyms and ambiguity enter the conversation.

As the person who often writes borderline-essay-length comment blocks explaining particularly spooky behaviors or things to keep in mind when dealing with a piece of counterintuitive/sensitive/scary code, my reason for mega-commenting is even simpler: all the stuff I put in comments should absolutely instead live in adjacent documentation (or ADRs, troubleshooting logs, runbooks, etc). When I put it in those places, people do not read it, and then they do the wrong things with the code. When I put it in comments, they read it, as evidenced by the rate of "that bug caused by updating the scary code in the wrong way happened again"-type events dropping to zero. It's easier to fix comment blocks than it is to fix engineers.

> I will completely forget why I wrote it that way.

This is the main reason for comments. The code can never tell you "why".

Code is inherently about "what" and "how". The "why" must be expressed in prose.

> For example, I am writing some driver software for a USB device right now. It is so easy to get the device into a bad state, even when staying within the documented protocol. Every time I implement a workaround, or figure out exactly how the device expects a message to appear, I put in a comment to document it. Otherwise, when (inevitably) the code needs to have features added, or refactoring, I will completely forget why I wrote it that way.

I believe in general there is a case for this (your case sounds like a perfect candidate). The implementation of Dtrace is another example[0] full of good description, including ASCII diagrams (aside: a case for knowing a bit of Emacs (though I'm sure vim has diagramming too, which I would know if I pulled myself out of nvi long enough to find out)).

[0] https://github.com/opendtrace/opendtrace/blob/master/lib/lib...

While I am not a Uncle Bob-style "no comments"er I do love a ridiculous method name. I pay very close attention to that method and the context in which it is called because, well, it must be doing something very weird to deserve a name length like that.

Sounds like you should instead be making these invalid states unrepresentable by encoding them in types and/or adding assertions. Especially if you're exposing them as interfaces, as your example function names would imply.

I don’t see anything wrong with those names. A bit hard to parse but the name moves with the function call while a comment does not.

It’s annoying to look at but when you actually read the function you know what it does. A more elegantly named function is less annoying to read but less informative and doesn’t provide critical information.

The name just looks ugly. But it’s like people have this ocd need to make things elegant when elegance is actually detrimental to the user. Can you actually give a legitimate reason why a method name like that is stupid other then its “hard to parse”. Like another user said… use snake case if you want to make it easier.

Encoding temporal dependencies (or exclusions) between methods is hard. You can get partially there by using something like a typestate pattern (common in rust).

Have you thought about distilling your hard-earned information about the device's behavior into a simulator for the device you could test your code against?

Implicitly, IIRC, the optimal ratio is 5-20:1. Your interface must cover 5-20 cases for it have value. Any fewer, the additional abstraction is unneeded complexity. Any more, and your abstraction is likely too broad to be useful/understandable. The example he gives specifically was considering the number of subclasses in a hierarchy.

It’s like a secret unlock code for domain modeling. Or deciding how long functions should be (5-20 lines, with exceptions).

I agree, hugely usual principle.

I believe that there is a genuine physiological effect that makes it a good idea to have the area of code that you need to think about fit entirely on one screen, without scrolling. There is probably an upper limit to the screen height where that limit is useful: I would believe a 100-line function to be above it and a 24-line function to be safely below it, but I wouldn't want to hazard a guess in the middle.

It's all to do with how your brain processes what it's seeing, and the planning processes involved in getting to the next bit of information it needs. If that information is off-screen, then the mechanisms for stashing the current state and planning to move your hands in whatever way necessary to bring it onscreen will kick in, and that's a sort of disfluency.

Similarly with tokens too far from whatever you're currently focused on. There's likely to be a region (or possibly a number of tokens) around your current focal point within which your brain can accurately task your eyes to scan, and outside that, there's a seeking disfluency.

I think this is why you get weird edge cases like k and j, where they pride themselves on having All The Code in one 80x24 buffer, and it actually works for them despite breaking all the rules about code legibility.

I think learning extremes can be useful, just don't take any one paradigm as gospel. Practicing Clean Code forces you to think in a special way, and when you've tried it, you start to get a feeling for where you should draw the line. Doing CC makes you a better programmer, but you have to figure out yourself where the tradeoffs are.

Other examples are TDD. Forcing myself to write tests for everything for a period has made all my code since better, even though I don't practice TDD now.

If you don't nest that much, big functions aren't so bad.

You can just scroll down and see what happens in a linear fashion.

As Ben Franklin wrote "the best physician that knows the worthlessness of the most medicines."

I don't know, I think the kind of person that comments on hacker news is not the average sort of programmer. I mentioned Clean Code to a more experienced colleague today and he had no idea what I was talking about, and when I mentioned the ideas to him he laughed at them. So I don't think there's some sort of pendulum swinging the other way and people are going to start writing massive functions. You'll probably just see small subcultures come up with some new idea that's obnoxious.

There have been some pendulum swinging around things like monoliths/microservices, but even then the amount of people that those things effected is actually much less than the larger community of programmers as a whole.

The warning sign I see when methods are split too much is that the method boundaries start to get messy: methods take too many arguments, or state is saved into confusingly named class members, or you end up returning some struct containing a grab bag of unrelated values.

It's been a long time since I've read the book but I took it to be less 'cut the function at X lines' and more 'long functions tend to be doing too many things at a time'. I think if you're able to give a good name to some sub section of a function, it's a good sign that it can be extracted out. At that point, you shouldnt need to look at the functions implementation unless its the specific function that you want to modify, because its name and arguments should be enough to know what it does and that you don't need to touch it.

Are we talking about the same thing and you'd still find that hard to understand?

> If you want to write good code, read good code.

As a junior in the field working at a small company, I often rely on this community for guidance, and this seems the most sound advice on this thread.

> You are left sifting through the ashes of your program wondering "Where did I go wrong?"

Brilliantly phrased metaphor, thank you.

>Each individual function eventually does zero things.

Lambda calculus, basically :)

it has been years since I read the book, but I'm surprised that there's so much hatred for it here. From memory it seemed like fairly harmless things like give things good names, try to make the code readable, dont comment what the code does but why, use consistent formatting, avoid duplication.

Other than people going overboard with empty classes and inheritance Ive not really seen a problem of people breaking down functions too far.

Which parts are important to grow out of?

> so bizarre ... what the hell is that supposed to tell someone?!

I liked this bizarre comment. It was like seeing a physical geometry proof for trig. Or like thinking about primes while riding a bike for an hour.

In 10 - 15 seconds this comment offered a flash of appliable intuition into primes I'd not appreciated before.

Granted, the bulk of that was first gathering that the top 3 rows of digits were a series turned sideways (printing them rotated would have made that instant). Joys of plaintext.

But then the pattern popped, and the code, including the optimization, made sense, but now from the "grok", with MTOWTDI.

Neither their commentary nor their function names and comments, caused the grok. I could "accept" the assertions, but to me neither naming nor comments were intuitively self-evident the way the diagram was.

Both of them commented on having to dwell on what the code was doing to consider refactoring. Once this flash happens, one no longer needs reference code at all, it's just another property of primes.

> I'm not unfairly clipping context away from it

Yes you are, you didn't attach the surrounding code where this comment was found. That comment would make a lot of more sense even just with the function name.

Lol, this reminded me of those engravings we put on spacecraft. Like, if we had to communicate the algorithm to an alien civilization then sure, this might be the best way to do it!

https://en.wikipedia.org/wiki/Pioneer_plaque

I'm pretty much in agreement with you on this, however I'm always aware of the possibility of comments being bugs. If code gets moved around, there is the very real possibility that the comment is now attached to the wrong method or line of code.

I now comment on method or function basis, describing what the method does. The how should be evident in the body itself.

He doesn't seem to often concede to being wrong.

Actually, I presented that figure as an example of just how difficult that problem was to understand, and how (on a bike ride) I was finally able to visualize what was going on. The ascii image was presented a bit tongue in cheek.

However, if you study that image, you might come to the same insight that I (on my bike ride) came to; and that the english comments never helped me with.

Once you notice that the primes are in the top rows, it becomes a pretty good comment.

Biased against the approach of your former coworker and thus the "Clean Code" way? I assume it did not work out well, because you needed to move fast to build an MVP before trying to do it right?

Let's not forget that Uncle Bob, by the time of writing "Clean Code" had 4 decades coding experience.

Because the pendulum of typing hadn't swung back to static being in vogue when the Philosophy of Software Design came out. At the time you had mostly the Scala & Haskell people standing in a corner screaming until they (well, we as I was one of them) were blue in the face about reducing "certain types of bugs", and making impossible states impossible.

Since then, everyone and their brother is on the static typing train. And from that lens you're right. It seems like an omission. Give it another 10 years and people will probably think the opposite.

That was exactly the approach taken by Prof. Ousterhout in setting up the class which lead to this book --- rather than just having students turn in working code for a grade, the code is reviewed with the student and the student then works to make it better --- in turn, the 2nd edition of the book was informed by the experience of teaching the class and the author actually changed his position based on the experience gained.

Type systems and type-based coding patterns are very hip right now, but they weren't 6 years ago. That is partly because the type systems in the main languages in use 6 years ago were hack jobs (to put it politely).

I do expect the pendulum to swing against type systems at some point soon for the same reasons it swung against OOP: Too much heavy lifting done by something that's hidden from the programmer, encouraging people to be "too clever," etc. Like OOP, algebraic types are a tool that have to be used well, and the current users are people who really like type systems and do use them well. It's only a matter of time before the tool gets into the hands of the average programmer, and then we will see how terribly a great type system can hurt you.

I've seen this in what I call 'lasagna code' - multiple thin layers that seem to do nothing (or almost nothing) but each one is an implementation of some abstruse interface that exists in the mind of the original developer.

Eventually, your code has to do something. Get that thing in one place where you can look at it in its whole.

John Carmack would disagree with Uncle Bob and John Carmack actually programs.

My own experience is that with an IDE that can collapse a new scope in the middle of a function, you can make large functions that accomplish a lot and are very clear by writing a comment and starting a new scope.

If something is going to be called multiple times a new function makes sense, but this idea that anything that can eventually return a single value needs to be it's own function is a giant pain that creates more problems than it solves.

Just makeing a new scope in the middle of the functions lets you use all the variables in the outer scope, do transformations without introducing new variables and ultimately "return" a new variable to the outer scope.

I've never understood why polluting namespaces with dozens or hundreds of names (most of which may not be very descriptive since naming a hundred small things is already going to be confusing) is seen as a good idea. You look at a list and you have no idea what is important and what was being shoved in there to satisfy some do nothing public speaker's arbitrary rules.

Too often I see functions that are shells that reshuffle the arguments and pass them to another function, which also reshuffles the arguments and forwards them to another, and on and on. One was 11 layers deep.

Yes. This works but only if the functions are pure and using pure function composition.

Uncle bob doesn’t mention this.

   createspecialString(y) =
       Capitalizefirstletter .
       MakealllowerCase .
       AddNumberSuffix .
       removeLetterA .
       removeLetterB .
       ConcatwithWord(x)

   CapitalizeFirstLetter(a) = a[0].upper() + a[1:]
   MakeAllLowercase(a) = map(a, (t) => t.lower())
   Addnumbersuffix(a) a + 3.toString()
   RemoveLetterA(t) = filter(t, (s) => s.lower() == “a”)
   RemoveLetterB(t) = filter(t, (s) => s.lower() == “b”)
   ConcatenateWithWord(x) = (y) => y + x

   

There see? It’s mostly doable in pure functional composition where the dot represents function composition. I program like this all the time. No way anyone can pull this off while mutating state and instantiating objects.

   F . P = (x) => F(P(x))

Forgive some inconsistent formatting and naming im typing this on my phone.

People who complain about this style tend to be unfamiliar with it. If you had knowledge about procedural coding styles and a function composition approach like this then usually this style is easier as the high level function literally reads like English. You don’t need to even look at the definitions you already know what this complicated string formatting function does.

No comments needed. And neither author tells you about this super modular approach. They don’t mention the critical thing in that this style requires functions to be pure.

Thus to get most of your code following this extremely modular and readable approach… much of your code must be minimizing IO and state changes and segregating it away as much as possible.

The Haskell type system, the IO monad is pushing programmers in this direction.

Again neither author talks about this.

There are. A lot of Java code bases look like this.

It is all as bad as you imagine. Functionality is spread out all of the place so it is very difficult to reason about how it all hangs together.

Yes, I've worked on a couple of codebases like that. It's glorious, you break everything down little by little and every step makes sense and can be tested individually. Best jobs I've had.

Like with a lot of his approach, its great for teaching people better coding skills in an educational setting, but doesn't make as much sense in the real world.

It is a bit weird.

However, a friend of mine was a professional Smalltalk programmer. He claims that his median line count of methods, over his 17 year career, was 4.

It is harder to do in other languages--it seems that C would be on the order of 10.

Clearly it is a rule that can lead to complexity of too many methods, compromising whatever gain smaller methods give you.

You should be baffled, because I never presented that as a hard and fast rule.

fwiw Lines-of-Code / Method (Digitalk V/286 image, 1989) = 7

https://dl.acm.org/doi/10.1145/74878.74904

This is something that's easier to read than it is to understand. A lot of languages force you to do quite a lot in a function and becoming blind to bloat is way to easy to do. (C++/Go/Java/etc yep).

He did an example in the article of:

void concurrentOperation() { lock() criticalSection(); unlock() }

So if you subsitute criticalSection with a lot of operations, such as open file, read lines, find something, close file. I think you have a better representation of an over bloated function.

Scala has the langauge support to show what this could look like.

What you're doing in that method is starting a critical section, doing something, and then ending a critical section. It's a good suggestion to break that with:

def criticalSection(f: () => Unit) { lock() f() unlock() }

How you have a single method that does one thing and is easy to understand. Also it's reusable.

The original code would be used as:

criticalSection { _ => doSomething() }

That replacement is now longer dependent on locking. Locking is layered in.

Honestly that kind of makes the word "clean" seem like a good fit to me. I can't say that measuring the cleanliness of my house is objective.

The Uncle Bob thing is something I'm experiencing right now.

I hired a friend who was a huge Uncle Bob mark, and he kept trying to flex his knowledge during interviews with other people in the company. I didn't really think much of it and told the other interviewer that it was just his personal quirk and not to worry much.

I had him work with some junior devs on a project while I took care of something more urgent. After finishing it, I went over to take a look at how it was going on his end. I was horrified at the unnecessary use of indirection; 4 or 5 levels in order to do something simple (like a database call). Worse, he had juniors build entire classes as an interface with a database class that was "wrong".

No practical work was done, and I've spent the past 4 weeks building the real project, while tossing out the unnecessary junk.

I liked Clean Code when I read it, but I always assumed a lot of it was meant for a specific language at a specific time. If you are using it verbatim for a Python project in 2025, why?

> I worry that his approach allows a certain kind of programmer to focus on like ... aesthetic, dogmatic uniformity (and the associated unproductivity of making primarily aesthetically-motivated, dogmatic changes rather than enhancements, bugfixes, or things that other coders on a project agree improves maintainability) instead of increasing their skills and familiarity with their craft.

Funny, I find the opposite. In my experience people that are willing to take a "dogmatic" position on code style are those who are able to actually get on with implementing features and bugfixes. It's the ones who think there's a time and place for everything and you need to re-litigate the same debates on every PR who tie themselves in knots getting nothing done.

Do I agree with absolutely everything Martin writes? In principle, no. But I'd far rather work on a codebase and team that agrees to follow his standards (or any similar set of equally rigid standards, as long as they weren't insane) than one that doesn't.

I'm not familiar with the Clean Code book etc; my introduction is the article. UB seems to be advocating consistently for patterns that are not my cup of tea! For example: Functions sometimes make sense as 2-3 lines. Often 5-20. Less often, but not rarely, much more than that!

I'm also a fan of detailed doc comments on every module and function, and many fields/variants as well. And, anything that needs special note, is unintuitive, denotes units or a source etc.

> It's striking to me how out of touch Martin seems to be with the realities of software engineering in this transcript

It was always like that. And Fowler the same thing with his criticism of anemic domain model. But software-engineering is no exceptions to having a mass of people believing someone without thinking by themselves.

I haven't seen a lot of evidence that Martin really has the coding chops to speak as authoritatively as he does. I think when you become famous for giving advice or being an "expert", it can be difficult to humble yourself enough to learn new things. I know personally I've said a lot of dumb things about coding in the past; luckily none of those things were codified into a "classic" book.

What strikes me about the advice in Clean Code is that the ideas are, at best, generally unproven (IE just Martin's opinion), and at worst, justify bad habits. Saying "I don't need to comment my code, my code speaks for itself" is alluring, but rarely true (and the best function names can't tell you WHY a function/module is the way it is.) Chopping up functions and moving things around looks and feels like work, except nothing gets done, and frankly often strikes me as being the coding equivalent of fidget spinners (although at least fidget spinners dont screw up your history). Whenever Martin is challenged on these things he just says to use "good judgement", but the code and advice is supposed to demonstrate good judgement and mostly it does not.

Personally I wish people would just forget about Clean Code. You're better off avoiding it or treating it as an example of things not to do.

I read Clean Code when I started out my career and I think it was helpful for a time when I worked on a small team and we didn't really have any standards or care about maintainability but were getting to the point where it started mattering.

Sure, dogmatism is never perfect, but when you have nothing, a dogmatic teacher can put you in a good place to start from. I admired that he stuck to his guns and proved that the rules he laid out in clean code worked to make code more readable in lots of situations.

I don't know anything about him as a person. I never read his other books, but I got a lot out of that book. You can get a lot out of something without becoming a devotee to it.

EDIT: I think even UB will agree with me that his dogmatism was meant as an attitude, something strong to hit back against a strong lack of rigidity or care about readable code, vs a literal prescription that must be followed. See his comment here:

> Back in 2008 my concern was breaking the habit of the very large functions that were common in those early days of the web. I have been more balanced in the 2d ed.

And maybe I was lucky, but my coding life lined up pretty neatly with the time I read Clean Code. It was an aha moment for me and many others. For people who had already read about writing readable code, I'm sure this book didn't do much for them.

I'm going to have to admit to never having read Clean Code. It's just never appealed to me. I did read some of UBs articles a fair number of years ago. They did make me think - which I'd say is a positive and along the lines you are putting forwards.

Rigidity and "religious" zeal in software development is just not helpful I'd agree.

I do however love consistency in a codebase, a point discussed in "Philosophy of Software Design", I always boil this down to, even if I'm doing something wrong, or suboptimal, if I do it consistently, once I realise, or it matters I only have one thing to change to get the benefit.

It's the not being able to change regardless, in the face of evidence, that separates consistency and rigidity (I hope)!

I don't know why people take UB seriously. He never provided proof of any work experience - he claims to have worked for just a single company that... never shipped any code into production. Even his code examples on GitHub are just snippets, not even a to-do app (well, I think that his style of "just one thing per function" works as a self-fulfilling prophecy).

Maybe people like him are the reason why we have to do leet code tests (I don't believe he would be capable of solving even an easy problem).

Another example of not quite pragmatic advice is Screaming Architecture. If you take some time to think about it, it’s actually not a good idea. One of the blog posts I’m working on is a counter argument to it.

> It's striking to me how out of touch Martin seems to be with the realities of software engineering in this transcript. Stylistic refactors that induce performance regressions, extremely long and tortured method names for three-line methods, near-total animus towards comments ... regardless of who is right/wrong about what, those takes seem like sophomoric extremism at its worst, not reasoned pragmatism that can be applied to software development in the large.

I think you're talking out of ignorance. Let's take a moment to actually think about the arguments that Uncle Bob makes in his Clean Code book.

He argues in favor of optimizing your code for clarity and readability. The main goal of code is to help a programmer understand it and modify it easily and efficiently. What machines do with it is of lower priority. Why? Because a programmer's time is far more expensive than any infrastructure cost.

How do you make code clear and easy to read? Uncle Bob offers his advise. Have method names that tell you what they do, so that programmers can easily reason about the code without having to even check what the function does. Extract low-level code to higher level methods so that a function call describes what it does at the same level of detail. Comments is a self-admission you failed to write readable code, and you can fix your failure by refactoring code into self-descriptive member functions.

Overall, it's an optimization problem where the single objective is defined as readability. Consequently, it's obvious that performance regressions are acceptable.

Do you actually have any complain about it? If you read what you wrote, you'll notice you say nothing specific or concrete: you only throw blanket ad hominems that sound very spiteful, but are void of any substance.

What's the point of that?

> Maintainability/appropriate factoring are subjective qualities that depend a lot on the project, the other programmers on it, and the expectations around how software engineering is done in that environment.

The problem with your blend of arguments is that guy's like you are very keen on whining and criticizing others for the opinions they express, but when lightly pressed on the subject you show that you actually have nothing to offer in the way of alternative or guideline or anything at all. Your argument boils down to "you guys have a style which you follow consistently, but I think I have a style as well and somehow I believe my taste, which I can't even specify, should prevail". It's fine tha you have opinions, but why are you criticizing others for having them?

> sheer rigidity

That looks more like a communication style difference than anything else. Uncle Bob's talks and writing are prescriptive -- which is a style literally beaten into me back when I was in grade school, since it's implied just from the fact that it's you doing the speaking that you're only describing your opinions and that any additional hedging language weakens your position further than you actually intend.

If you listen to him in interviews and other contexts where he's explicitly asked about dogmatism as a whole or on this or that concept, he's very open to pragmatism and rarely needs much convincing in the face of even halfway decent examples.

> animus toward comments

Speaking as someone happy to drop mini-novels into the tricky parts of my code, I'll pick on this animus as directionally correct advice (so long as the engineer employing that advice is open to pragmatism).

For a recent $WORK example, I was writing some parsing code and had a `populate` method to generate an object/struct/POCO/POJO/dataclass/whatever-it-is-in-your-language, and as it grew in length I started writing some comments describing the sections, which for simplicity's sake we'll just say were "populate at just this level" and "recurse."

If you take that animus toward comments literally, you'll simply look at those comments and say they have to be removed. I try to be pragmatic, and I took it as an opportunity to check if there was some way to make the code more self-evident. As luck would have it, simply breaking that initial section into a `populate_no_recurse` method created exactly the documentation I was looking for and also wound up being helpful as a meaningful name for an action I actually wanted to perform in a few places.

That particular pattern (breaking a long method into a sequence of named intermediate parts) has failure modes, especially in the hot path in poorly optimized runtimes (C#, Java, ..., Python, ...), and definitely in future readability if employed indiscriminately, but I have more than enough experience to be confident it was a good choice here. The presence in my mind of some of Uncle Bob's directionally correct advice coloured how I thought about my partial solution and made it better.

> other animus

- Stylistic refactors that induce performance regressions can be worth it. As humans, we're pre-disposed to risk avoidance, so let's look at an opposite action with an opposite effect: How often are you willing to slow down feature velocity AND make the code harder to maintain just to squeeze out some performance (for a concrete example, suppose there's some operation with space/time/bandwidth tradeoffs which imply you should have a nasty recursive cte in your database to compute something like popcount on billion-bit-masks, or even better just rewrite that portion of the storage layer)? My job is 80% making shit faster and 10% teaching other people how to make shit faster, but there are only so many hours in the day. I absolutely still trade performance for code velocity and stability from time to time, and for all of those fledgeling startups with <1M QPS they should probably be making that trade more than I do (assuming it's an actual trade and not just an excuse for deploying garbage to prod).

- The "tortured method names" problem is the one I'm most on the fence about. Certainly you shouldn't torture a long name out of the ether if it doesn't fit well enough to actually give you the benefits of long names (knowing what it does from its name, searchability), but what about long names which do fit? For large enough codebases I think long names are still worth the other costs. It's invaluable to be able to go from some buggy HTML on some specific Android device straight to the one line in a billion creating the bug, especially after a couple hiring/firing sessions and not having anybody left who knows exactly how that subsystem works. I think that cutover point is pretty high though. In the 100k-1M lines range there just aren't enough similar concepts for searchability to benefit much from truly unique names, so the only real benefit is knowing what a thing does just from its name. The cost for long names is in information density, and when it's clear from context (and probably a comment or three) I'm fine writing a numeric routine with single-letter variable names, since to do otherwise would risk masking the real logic and preventing the pattern-recognition part of your brain from being able to help with matters. HOWEVER, names which properly tell you what a thing does are still helpful (the difference between calling `.resetRetainingCapacity()` and `.reset()` -- the latter you still have to check the source to see if it's the method you want, slowing down development if you're not intimately familiar with that data structure). I still handle this piece of advice on a case-by-case basis, and I won't necessarily agree with my past self from yesterday.

> "Uncle Bob devotees" vs "Uncle Bob"

This is maybe the core of your complaint? I _have_ met a lot of people who like his advice and aren't very pragmatic with it. Most IME are early-career and just trying to figure out how to go from "I can code" to "I can code well," and can therefore be coached if you have well-reasoned counter-examples. Most of the rest IME like Uncle Bob's advice but don't code much, and so their opinions are about as valuable as any other uninformed opinion, and I'm not sure I'd waste too much time lamenting that misinformation. For the rest of the rest? I don't have a large enough sample I've interacted with to be very helpful, but unrelenting dogmatism is pretty bad, and people like that certainly exist.

[dead]

Rewrite is only useful it you get something else that you can't get otherwise. Mixing Rust and C++ in a project is hard but doable - odds are if you try it you will find enough "friction" that eventually it will be worth rewriting to get rid of one.

That book really poisons the mind. Even if there's some good things to learn in there, it's stashed among a lot of advice that is either plain bad or needs asterisks. But there aren't really any asterisks and instead it presents what look like rules that you shouldn't be breaking if you want to be a good programmer.

When I first read the book I'd already been programming for 10 years, but I was in my first job out of college. I'd heard a lot about the book and so I trusted what it had to say. I let it override how I would have written code because I figured coding professionally was just far different than what I would consider the best way to write code.

Interestingly, 5 years sounds about right for how long it took me to finally start trusting my own judgement. I think it was a combination of being more confident in myself but also because I was doing larger projects and it was more frequent that I was putting down a project and then coming back a couple months later. That's how I was able to see how bad the code was to work with once my mental model of it had flittered away.

Now I take a much less strict approach to my code and I find it a lot better to work with later.

"john ousterhout's book is the only book on how to write software that has any actual evidence behind it."

This is false and hopefully no one takes you seriously when they read that. There are books about empirical methods for software engineering, for example, which actually seek to find real evidence for software engineering techniques. See Greg Wilson's work, for example.

There are lots of other architecture/design books that use real world systems as examples. "Evidence" is definitely lacking in our field, but you can find it if you try.

5 years is about right.

when i found a copy of clean code in a bookstore, it only took me a few minutes to put it back. I had read John Ousterhout's book prior.

In typical HN commenter smugness. It took me less than that to realise it was bullshit. It didn’t make things clear, it made them more abstract and more resistive to change. Similarly with DDD. Just build what you need and deal with the consequences of inevitable change later. No one cares if you miraculously perfectly modelled your “definitely the final form” of your domain from day 0.

Oh and TDD?! Ah yes those perfectly defined unit cases you write for implementation details. The best comment I read recently (sorry I can’t find it) something akin to “The first unit I write is to validate the intended side effects through properly exercising associated mocks”

As with everything there is no “best way” to do something, but in software engineering… there are far more bad “best ways” than best “best ways”

The more I tried to implement Clean Code, the more it helped me appreciate Worse is Better approach, which comes from an observation, not a dogma: while all programmers strive for simplicity both in implementation and interface, when they come into conflict, simple implementation usually wins over simple interfaces, as they are easier to modify.

https://dreamsongs.com/RiseOfWorseIsBetter.html

I don't understand how that works on people. Dog whistling, "Hey, hey, leave me to my grift."

Philosophy of Software Design seemed more pragmatic to me.

I also fixed the disassembler to also add a clickable link to the instruction spec page for each instruction.

He also works with a lot more students, with student-sized projects and problems and code lifetimes. He's used his book for classes, I think it's on a level appropriate for a freshman.

Both books are bad, but APOSD is my most disliked technical book ever. CC is at least interesting as an exercise to see that critics are way too uncharitable. Kernighan and Pike's The Practice of Programming is far better than either. And https://antirez.com/news/124 is one of the few good discourses on comments out there, something as a profession we care way too much about when the cost of doing it "wrong" is typically so low.

I wouldn't recommend Code Complete today; I think The Practice of Programming covers most of the same material, is much shorter, is much better written, and isn't tainted by McConnell's later embrace of snake-oil methodologies, some of which made it into the second edition of CC. TPOP didn't exist when CC changed my world.

I read Clean Code and don't remember a single thing from it. To be fair it was a while ago.

But the SOLID and Clean Architecture principles inform me almost daily.

Software is unusual in that it's never finished. This makes ease of modification a critical quality of software in a way that it isn't for Formula 1 race car engines or most buildings.

Ease of modification was one of the top priorities in the design of the Model T Ford, because cars break down and must be repaired, and a car that is difficult or impossible to repair will cost its owner large sums of money. Software doesn't break down (though online services do) but for other reasons modification is a high priority.

Perhaps short-lived buildings don't need to be easy to modify, especially if the architects have a very good understanding of the needs of the users over their lifetimes. Often that is not the case, though, and Christopher Alexander was famous in large part because much of his career was devoted to figuring out how to enable inhabitants of buildings to modify them more easily, so that their needs would eventually be met even if the architects guessed wrong decades in the past. Centuries-old stone farmhouses exist, too, and ease of modification is crucial for them; if they cannot be modified they cease to function in only a century or two at most.

Whatever the goal of your software, it is crucial for the people who are modifying it over time to achieve that goal to be able to understand it.

A genius architect/Formula 1 engineer can design a building/engine that fits all the requirements astonishingly perfectly, but if the builders have difficulties understanding it, or later contractors can't figure out how to maintain or fix anything, then it's only a perfect design in theory and an awful design in reality. It's not a nice-to-have to make people's lives a little easier, it defines the success of the project. The genius architect/engineer can insist that the complex design reflects the underlying domain as much as they want but at some point they will have to back that up to someone else who isn't a genius.

Obviously, writing code such that a first year comp sci student can understand what's happening and can start contributing immediately is absurd, but at the same time nobody builds anything in a vacuum. There's a certain legibility required within any context you're designing something for.

Most people aren't building Formula 1 cars. Buildings are a better analogy: they are designed to be maintained. You can replace a door handle without replacing the door or the wall, you can turn off the power to different sections to do repairs. Dangerous or complex parts are labelled, moved into their own rooms or cupboards, and locked.

This is what the soft in software means. It needs to be able to be adapted and change with its requirements.

My favourite story from a previous job was working with high-speed scanners, OCR, data quality, typo correction - that kind of thing.

The pipeline did its job well enough. But later we got a new contract where we accepted email submissions (where the customer had scanned stuff themselves). The guys couldn't hook that into the pipeline, so they set up a new pipeline - to print out the emails so they could then be scanned into the existing pipeline.

I still get a good laugh about that to this day.

Writing software is more akin to building an engine factory than a single engine. At least, much of business software is used over a long period with lots of changes needed. Maybe writing a single game is more comparable to the race engine.

Yes, no, I think he has different mental capabilities than most (most of the commenters here at least) and by that actually are living in a different reality. Human brains function vastly different. Two examples stood out to me.

1) UB said he reads the code in its full from left to right with the if(isTooHot) example. I only resort to reading code in that way as a last resort if I really can't figure out what the code is doing. I mean I look at a block or row and take it in more as a whole.

2) UB said comments are annoying because he has to read them and keep the whole of the comment text in his mind. This again says he reads everything left to right, and he can likely store everything that he has read up to a certain amount.

My mind works nothing like that. I can hold very few words in my working memory but can instead hold concepts/ideas. For that to work good I need to see as much of the involved code as possible and my mental image evaporates if I have to navigate too far where I started.

Uncle Bob has been a horrible influence on our industry, and we’re expressing that. He has not actually worked on anything but yet he’s been able to make some money selling his inexperienced opinions.

> This would be so much better as a single method/function with a few interspersed comments that explain the algorithm.

I haven't read the whole article when I wrote that comment. Turns out that Ousterhout provides a rewritten version of "PrimeGenerator" that does exactly this. At least UB concedes that this version is indeed much better.

Knuth?

He has argued in the past that the concept of Literate Programming

http://literateprogramming.com/

is the most important work he has done, and I highly recommend his various collections of lecture notes/papers including:

https://www.goodreads.com/book/show/112245.Literate_Programm...

A Discipline of Programming, Dijkstra

The architecture of Concurrent Programs, Per Brinch Hansen

Literate programming--see http://www.literateprogramming.com/

I don't recommend Design Patterns, as these are elements needed if your programming language is inadequate.

There are many more.

FWIW Uncle Bob has been preaching functional for more than 10 years now.

https://youtu.be/7Zlp9rKHGD4

I'ma big Tcl fan, but Ousterhout has created many other important things - see https://en.wikipedia.org/wiki/John_Ousterhout .

Curious what Stallman has to say about Robert C. Martin --- looked, but couldn't find anything....

philosophy is the basis of reason, math, and science. it's sad that "engineers" don’t understand it or it's import.

It's an improvement over demagoguery and blind rule-following.

Moreover, the book argues for engineering principles (in pretty much all possible senses of that phrase).

An interesting contrast to it is Ousterhout's observation:

>If you can visualize a system, you can probably implement it in a

>computer program.... This means that the greatest limitation in writing

>software is our ability to understand the systems we are creating.

Though interestingly it is in marked contrast to a different statement in the "Software Design Book" Google mailing list:

>John Ousterhout, Aug 21, 2018, 12:30:15 PM

>I've never felt that graphs are a particularly useful way of describing software structure.

>The interactions between classes end up so complicated that the graph becomes an unreadable mess.

>Also, I'm not sure that the complexity of a graph representation of software correlates with its

>practical complexity (the graph representation might look very complicated, but the software might

>still be pretty easy to maintain).

and I'd be interested if someone knows of a text/video/interview which resolves that twain, or what sort of visualization is advocated for/recommended.

https://github.com/unclebob/fitnesse

My problem with UB is that by promoting his brand and his style so much to junior developers (in both subtle and fairly overt ways), he's warped the mind of a lot of people in a way that effects them for a long time and the people around them. I don't really have anything personally against UB, but dealing with the code that one of his acolytes creates is deeply frustrating and often they claim it's "best practice" even though there's basically no validation around most of his claims and if you read the criticism, they're fairly common sense.

You guys really hated that I found the discussion interesting?