Clean Code vs. A Philosophy Of Software Design

Well said!

Honestly, no better indication of a very mediocre developer

    > 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.

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

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.

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.

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.

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.

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.

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.

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.

Made every engineering planning session a pain in the ass.

Was often quite wrong and always infuriating.

"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.

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.

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.

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

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?

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.

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.

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.

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.

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".

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.

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.

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...

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.

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.

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.

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

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.

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.

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

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.

Lambda calculus, basically :)

Brilliantly phrased metaphor, thank you.

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?

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

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.

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 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.

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.

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.

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.

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.

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

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.

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

   

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

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.

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.

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.

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

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).

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'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.

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.

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.

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.

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 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 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?

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.

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.

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”

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.

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.

https://dreamsongs.com/RiseOfWorseIsBetter.html

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.

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

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.

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.

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.

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.

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.

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...

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.

https://youtu.be/7Zlp9rKHGD4

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

>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.