It's probably time to stop recommending Clean Code (2020)

Absolutely but this isn’t the situation I’m talking about here.

To reuse your analogy, I’m talking about a restaurant who has a mess of an installation, several panels and breakers, not all up to code, and the electricity frequently shuts off taking hours to figure what happened and how to restore it. It’s also a mild fire hazard and there have been a few close calls that could have burned the place down.

The son in law, a hobbyist electrician, did the installation and extended it for free while the business was starting up and growing. He didn’t do it right but it works and got the restaurant so far.

Now the restaurant is very popular but the constant blackouts are driving people away and hurting profits. The mild fire hazard and not following code irks the authorities and insurance companies and they’re threatening closure. It needs an extra stove to keep up with customer demand but no one can figure out how to hook one up to the existing rats nest, let alone do it safely.

The owner knows this is a problem and is looking for a proper electrician to fix the mess.

In real life, I’d expect the business owner to agree with the electrician on a plan so that either the retaurant stays open (maybe at a lower capacity) so that the tidying up can happen gradually, or close down for renovations for a while so the whole thing can be overhauled quicker.

But what happens in our industry and in my experience is that instead the restuarant owner asks the electrician to tighten a screw or two here and there so that this power socket isn’t as wobbly anymore but then demands even more additions to the janky system and demands they be done as fast and cheap as possible as this is now the top and only priority.

Nothing really improves but the owner (at least for a while) can hide it from the authorities and insurance company because he has a quote and a specialist working on the system. Then the owner can blame the electrician because “he wasn’t able to balance fixing up the installation while extending it, so we’ll fire him and look for someone actually good this time”. Rinse and repeat ad nauseam.

Let’s say my site has a download image feature that embeds per-user digital licenses into downloaded images at download time. This might take some processing so there is a queue and an abstraction representing the downloaded file. There are also several endpoints serving different types of image files.

What shall I call the unit of code orchestrating these download processes, if not ImageDownloadManager?

> CRUD-type projects with very few interesting design decisions to be made about what the software should do computationally.

Isn’t this by far the bulk of code businesses produce and need though? Very few businesses actually have the scale or product that requires more than a glorified CRUD with arcane business rules slapped on top.

> code should be correct and easy to understand. I think “correct and easy to understand” is a much more useful rubric than “clean”. Obviously it’s still subjective. Code that is easy to understand for you may be hard for me to understand.

There's a deeper problem here that has driven a lot of disputes over the years.

"Ease of understanding" is not a stable property of code. If you have two separate pieces of code that are easy to understand, and the only thing you do with them is combine them, your resulting one piece of code may also be easy to understand.

Or it might be next to impossible to understand.

> Like, “you shouldn’t use boolean flags as parameters, you should use enums” becomes “I can‘t understand the meaning of true/false at the call site, so let’s use an enum instead”.

That's not the reason to use enums instead of parameters for functions, rarely will you not be able to understand what the bool arg means in:

  create_user(..., is_admin: bool)

If you don't then you need a better IDE.

The reason to use enums and for that matter structs is that as requirements evolve, inevitably you will need to extend the code base and at some point `is_admin` alone won't cut it, you'll need an is_moderator etc.

This leads to two things, one is function signature pollution and unnecessary extra validation code, eg. what happens if both is_admin and is_moderator are set?

What about the functions relying on the old signature? Perhaps you make separate versions of the functions, eg. create_admin_user and create_moderator_user and keep the old one with the flag, then you can keep backward compatibility...but at the cost of an api that makes people go insane when using it.

More likely you'd then go to an enum which leads backward incompatible changes, and likely a refactor, which in the event of a library can break dependent code and in all cases is a lot more work than just using an enum in the first place.

Try to write code for the future reader and writer of the codebase. An enum will allow readers to immediately understand that there is a [normal, admin] distinction and adding a moderator would be as simple as adding a [normal, moderator, admin] in there.

Then, assuming you've written your code in a proper manner, your IDE will tell you all the places where a moderator needs to be accounted for in the code base.