> Clever code isn't usually good code. Clarity trumps all other concerns.
Generally this is true, but with the caveat that what actually matters is 90th percentile (or maybe even 99th percentile) complexity. If you have a choice between spreading low-grade complexity across the codebase or having one module that is nearly incomprehensible but that provides an abstraction that makes the rest of the code very simple, the latter is almost always to be preferred. Once you've distilled out the evil into one place and gotten it working reliably, chances are you're never going to need to touch it again, and if you do need to, at least you only need to deal with it in one place.
If I understand what you're talking about, I tend to disagree - I've had a bad experience in general with "pure abstraction" layers in projects. It sometimes seems like a good idea to have this "magic" component which automates everything and takes care of all the hard stuff, but in practice it creates a whole host of problems.
For instance, maybe it works at first, and then your requirements change in a way that doesn't fit the abstraction. Now you can't make local changes, you've got to change this super complicated abstraction layer, and suddenly it requires changes all over the place in completely unrelated components, because you had to add an argument to `super_general_magic_function_that_is_used_everywhere()`.
Also things like this tend to make code super hard to trace. Instead of stepping through your functions, now all your tasks are running through some generic scheduler or something, which is there because somebody had the idea that if you ever need to run your code on a Hadoop cluster this would help, even though your code has only ever been run on a Raspberry Pi.
My rule for major new abstract components is: “if you’re going to do that, you have to get it right”.
It’s fine to have a major abstraction, but it needs to actually make a problem space disappear, for some definition of “entirely”.
That means:
- great code
- great documentation
- tested
- engineering resources assigned to maintain it full time
... for as long as it takes. Until you reach that level of “makes the problem space disappear entirely”.
So when someone suggests a new abstraction, I just ask if we’re going to invest all of that. And if not I suggest we stick to just using the tools we already have.
Interesting problem. I'm not convinced but don't have strong opinions on this. I feel nobody wants to touch the high grade complexity code so it would rot. Ultimately, reading code dominates writing it, so having low grade complexity spread around seems better as the bar for reading is lower
On some project I have used this method. It us usually one or two pure functions in a single file littered with comments. It is a complete abstraction, so it has absolutely nothing in common with the DB / UI code.
Every once in a while I have to touch it. Then I ignore everything else and just focus on this one part. Pen and Pencil is the most valuable tool for this.
Generally this is true, but with the caveat that what actually matters is 90th percentile (or maybe even 99th percentile) complexity. If you have a choice between spreading low-grade complexity across the codebase or having one module that is nearly incomprehensible but that provides an abstraction that makes the rest of the code very simple, the latter is almost always to be preferred. Once you've distilled out the evil into one place and gotten it working reliably, chances are you're never going to need to touch it again, and if you do need to, at least you only need to deal with it in one place.