1) To understand the system without necessarily wanting to change anything. This is common with new employees or anyone wanting to learn more.
2) The system often needs tweaks, bug fixes or new features. Each of these normally requires that the code in question is read by several people several times.
3) The architecture is normally not perfectly modular, so changing one part often requires one to understand and tweak the neighbouring parts of the system, too.Building good abstractions requires: 1. skill that is in relative terms rare in the profession; 2. enough experience with the problem domain that the abstraction provides the perfect balance between ease-of-use and flexibility as the context changes; 3. a dedicated individual or a small team who nurtures and gatekeeps the evolution of the abstraction obsessively.
For the other 99% of real world cases, the best you can do is try your best to build decent, not-too-leaky abstractions for the problem as you face it today, and the underlying code better be readable because you'll need to maintain it constantly, as will all kinds of other people in varying states of cluelessness.
Similarly, I think the author is simply saying that well written, easy to read, easy to understand code shouldn't have to be re-read multiple times by the same person. Which is good. The inverse would be that difficult to understand code would have to be read, re-read and studied deeply to actually grok. And thus read a lot. Which is bad.
i offer the entirety of sqlite as a counter-example. Based on that project's forum traffic and my participation within that project, i estimate that there are hundreds, if not thousands, of people who actively read that project's C code. That doesn't make it "bad code," that just makes it code which people want to understand (which, in turn, requires reading).
Like so: http://underscorejs.org/docs/underscore-esm.html
It goes back to IBM days where annotated code would ship in hard binders and was meant to be flipped through.
Sadly this has not caught on. How do you guys go spelunking in interesting codebases? I always wonder why there's isn't more tooling around this.
https://literateprogramming.com/
(or if that's off-line, see: https://en.wikipedia.org/wiki/Literate_programming )
and published books which exist so that folks can read the source code of programs:
https://www.goodreads.com/review/list/21394355-william-adams...
Code that does what it should is rarely read. Until you need to change it. And it may not be changing due to it being incorrect. If an attendant system gets replaced, you may have to change all the other systems it has touched. Business requirements may have changed. Stakeholders may have changed.
There are plenty of reasons for code to change beyond there being a bug.
Peter Seibel repeatedly tried to start "code reading groups", but found that they didn't quite work, because while everyone agreed that there was much to be learned from code bases, and that many advised "reading" code, most real code doesn't support "reading" so much as "decoding" or perhaps interactively exploring.
https://gigamonkeys.com/code-reading/
Robert Heaton had a fun post about code reviewing without being able to actually read the specifics of the code. With only a blurry view of the structure of code, one can get a sense of its likely virtues and opportunities for improvement. https://robertheaton.com/2014/06/20/code-review-without-your...
Kind of in the spirit of both, I love code where you don't _have_ to read most of it because:
- class names, generic parameters, etc, make it clear what classes represent
- method names and signatures make it clear how they're to be used; there are no surprises or gotchas in the specifics of the implementation that foist cognitive complexity onto callers, etc
- the right amount / granularity of structure exists, such that when you do need to read something, the section is moderately sized; there's not some enormous, entangled method that's actually doing 5 things at once. Modularity limits the scope of reading.
But also, when you do need to understand implementation specifics, good code acknowledges that reading is likely not "enough"; good code gives straight-forward on-ramps to interact and experiment with it. It doesn't force you to hunt for a bunch of environmental variables, configurations that are examined by an IoC layer, or magically materialize a file containing a specific serialization of a well-formed record just to invoke.
You can have an stinky old piece of legacy software that no one ever reads because that system is deprecated and slowly getting phased out, and we can live with it in the meanwhile.
You can have the most elegant a beautiful piece of code that gets read a lot, because it is in the critical path of a very active and rapidly evolving system, and people need to reference, modify and extend it a lot.
However there is a crucial way where OP is wrong: there is a pull and push between code quality and how often it is read. If your code is a legacy big ball of mud, people will be less inclined to touch it, probably going to the extend of rewriting the whole thing. On the other hand when code is well written, people are less afraid of digging into it.
Lastly, even if OP thesis was correct, I don't know think it would change anything. Strive to write the best code you can within reasonable constraints, independently of how much other will read it (which in my experience is almost always underestimated).
The bad code is read a few times and refactor as soon as we get a chance.
The best code and code bases allow you to quickly understand how they are structured and don't necessarily hold subtle, nasty surprises - or at least make it obvious if something is a nasty, subtle surprise. Those code bases tend to be a quick read.
The bad functions and code bases require you to carefully consider every little aspect of every single line in detail. And I don't just mean "read every line", I mean "Dissect lines based upon language specs, and also keep in mind this is interacting with 5 different other parts of the code base. Or not. Who knows?" In such code bases, just figuring out what something does tends to be a slog.
There’s a similar concept in management where the ineffective team requires additional staff to complete their work, which means that their culture “infects” the majority of the employees in the organisation.
Once I noticed this pattern, I can recognise it everywhere.
E.g.: JavaScript gets an enormous amount of industry attention because it is so inefficient and clumsy. If it was a good, mature language it wouldn’t need an endless parade of libraries, frameworks, tools, blog articles, vendors, and tutorials.
In game development, my primary field of expertise, the notion of a static codebase is largely a myth until the project nears completion. Most projects span several years, during which the code undergoes continuous evolution.
In this context, code must be as fluid/malleable as possible, because its entire structure is likely to change several times, to add and remove features, to improve performance, to fix bugs and sometimes for even deeper rework.
If the already written code is hard to read, these iterative modifications become unnecessarily arduous.
"Good code is rarely read twice."
This is a poor world view and is what leads to unwieldy systems with weird interactions that are buggy in just the right situation.
I understand what the author was trying to express, but the sentiment is poorly expressed. They conflate "used"/"run" with "read" several times. IME, good code is readable code, but not all readable code is good code. Clever code is normally much less readable. At the end of the day, the lifecycle of any code you produce is such that it will generally be maintained far beyond the time is was written. To me that means you need to write code with maintainability in mind. If you cannot read and understand the code, how can you expect the effectively maintain the code?
Simply having a clearly defined function name, arguments, and documentation doesn't mean you can ignore making the innards maintainable.
Finally, as others have pointed out, you want your colleagues reading good code so they can learn to write better code. No matter your level, you should never stop learning to be a better developer.
The compiler will probably optimise those extra lines out, but if not, I consider it a cost worth spending to make my life (or somebody else's life) easier in the future.
Also about the claim that that 10x programmers are fantasy, I call your attention to Fabrice Bellard https://bellard.org/. I have also worked with one or two in my decades of programming career. I probably peak out at somewhere around 0.75.
Not doing code review on a collaborative project? You're already setup for failure...
OP's point of view is valid if they are the only one working on the project. Only you are responsible for your low standards.
Unfortunately in the corporate world the people with the required clout rarely want to spend the time necessary to enforce a style.
Good code in my systems are ones that don't need to be touched or read very often, and the fluid/unknowns parts are decoupled elsewhere. Sometimes business requirements issue, Sometimes difficult technical problem.
So readable well commented code is not optimisation for common case. It is for an edge case.
God help you if you are investigating something bad, open code and see fast inverse square root - style code.
How does the author presume to know how to use something without being able to read it's interface or related documentation? The very things that make something easy to use, like clearly naming things, also makes it easy to read.
I would even argue that reading what the underlying code does is always good practice. Even if you think you know how something works, confirming it can avoid nasty bugs. Not to mention all the projects that are non-trivial and have enough complex behavior that reading the code is the best way to understand what it does; where there is no other way for it to be easy to use according to the author. There's also lots of other benefits, such writing code that is more consistent and more semantic with the underlying style.
Just horrible, horrible advice.
(also couldn't help but think "this is not the code you're looking for. move along.")
So basically, code can be both good and bad. It just requires that someone opens the box? Schrödinger's code.
I think I'll stick with my own definition, thank you.
Good code: works as expected, strives to be secure, strives to be bug-free, is reasonably efficient for the context it aims to be used in, is concerned with maintainability (this is where readability comes into play).
This means that core algorithm bundles in business applications that necessarily carry a lot of complexity and need lots of careful maintenance over the decades can never reach the status of good code.
On the other hand, the twenty lines of bash I use to hook mpv into SomaFM streams are very good code.
> In conclusion, good code is rarely read. Good code is so ergonomic that you almost don’t need to read it; you just use it. It allows developers to focus on building features and solving problems rather than deciphering existing code. This is the ultimate goal of good coding practices: to create code that is so clear and intuitive that it almost disappears, allowing the functionality to shine through.
The problem I have with this formulation is that it seems highly unlikely that removing "write readable goal" as a first-class concern alongside "write good code" will produce code with more efficiency or quality; at best, you'll end up with the same amount of bugs and readability, but at worst, you'll be producing code with at least as many bugs that's less readable, which in the long run will increase the amount of work to fix the bugs that are found. Reframing the problem in terms of minimizing how much code needs to be read doesn't seem like it would end up improving the outcomes, but it does seem like it's measuring something that's so hard for people to actually estimate correctly that focusing on it will end up making the outcomes worse by the very metric it tries to use.
Good or bad, you’re going to end up needing to add new features to this code. Or someone misunderstood an input or output to/from this code and you’ll need to read through it to understand how it’s implicated in a bug.
I think ‘good code is easy to read’ is pretty profound: DRY code with the right abstraction is easy to read. DRY code with the wrong abstraction is hard to read.