7 ms·

Good code is rarely read

104 points by alexmolas 2y ago

m463 2y ago
I was kind of wondering. Can bad code be rarely read? Or can easy to read code be bad? (also couldn't help but think "this is not the code you're looking for. move along.")
davydm 2y ago
I don't think the author has worked on long-lived projects. Eventually, all code is revisited because there's always shit to get done.
- bena 2y ago
  Not just long-lived projects. Working on bespoke, internal systems means you’re never truly done. And what you’ve done a month ago may not be what’s wanted now.
- madsbuch 2y ago
  Exactly my thoughts. The reason why good code is code that is easy to read, is because products evolve, and so does the code. Suddenly the taxonomy of that enum starts to shift, and the name that was perfect yesterday does not make sense tomorrow. These changes happen gradually and a basic acceptance of the code base not being on par with the product understanding is necessary in order to have any kind of velocity on not only spend time refactoring.
  - m463 2y ago
    I disagree. "good code is easy to read" - that does not work. I can write a bubble sort instead of quicksort and that code will be bad. Maybe you can do the same thing with privacy policies. Most complicated privacy policies are bad, so they make them hard to read so that people do NOT understand them and give up. But you could have a privacy policy that is bad and easy to read. "We can do anything". I think good code is primarily easy to read. And I think it should not attract attention through bad behavior, so it should additionally not come under scrutiny for that.
    - madsbuch 2y ago
      Of course your code should live up to requirements and be correct, for it to be good - The requirements can also be performance requirements. If you have a list of maximally 10 elements that needs to be sorted and you opt for quicksort over bubble sort in a context where bubble sorts time/space guarantees perfectly solved the requirements, well, then you absolutely wrote bad code. This is what a more senior developer understands, where a junior would jump in and write worse code.
- jeremywho 2y ago
  I don’t think you read the whole article. I had the same thought as you from the headline, but they gone on to state that good code is so easy to read when you need to make changes that you don’t have to go through it multiple times to make the required changes.
- chaboud 2y ago
  I had a similar reaction while reading this, something along the lines of “well, that’s a bunch of idealistic tripe”. And, honestly, I think that somewhat holds. That said, as an aim, writing readable code that doesn’t need to be read to be used is a good one. I wrote as much in a quora response almost a decade ago to the question “how does one become a great coder” ( https://www.quora.com/How-does-one-become-a-great-coder-programmer/answer/Matthew-Chaboud?ch=15&oid=12759472&share=5db82526&srid=vWzg&target_type=answer https://www.quora.com/How-does-one-become-a-great-coder-prog... ), and I think it still holds. However, the other part of that answer was to make the code immensely readable, because we read more code than we write unless we’re incredibly junior or comically superhuman.
- wglb 2y ago
  I did a consulting gig at Allstate around the time of Y2K. I chatted with a senior architect who had been with the company for over 20 years. He noted that there were such a vast array of programs and systems in place, some of which had been running for at least 40 years. I wonder if any of that code had been read, good or bad, for decades. And I am willing to bet that the source code for some of it was lost. This of course led to no small level of anxiety during the run up to Y2K. As a side note, while I was there, the dictum came down that there was to be no more assembler programming to be done. I know what you are thinking. They should just burn the mainframe with fire and rewrite it all. I recommend the book https://www.amazon.com/Kill-Fire-Manage-Computer-Systems/dp/1718501188 https://www.amazon.com/Kill-Fire-Manage-Computer-Systems/dp/....
- drewcoo 2y ago
  The long-lived projects I've seen have some code that mostly works that doesn't have any tests and is hard to grok. Nobody touches it because 1) any change might break something unexpected and 2) if you touch it, you might end up owning it. I wouldn't call that good code but it's often too good to spend time replacing.
- weebull 2y ago
  There's a class of code where you never need to read it because it's effect is well understood and it does it without problems. It has the right level of abstraction to be useful in multiple places and not specific to a singular case. It's not going to be top level code, but it's a building block you know you can rely on. This is something I think functional styles of programming lead more naturally towards than OO or procedural. It's far easier to separate concerns when you can pass around like bundles of functionality (i e. first order functions). Also it really helps when you are used to writing code with no dependency except what is passed in, and not effect except what is returned. Then thhen you're sure that the code is not leaky in it's abstraction. You can do it in other paradigms, but it's it's not where the language naturally leads you. OO has retained state as a key foundation of it's philosophy. Procedural code tends to mix up the how something is done and the what is being done. (e.g. the iteration through a data structure, with the definition of what is being searched for).
  - deleted 2y ago
    [deleted]
bena 2y ago
I don’t think this is a good rule of thumb. 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.
- jeremywho 2y ago
  I don’t think you read the whole article. I had the same thought as you from the headline, but they gone on to state that good code is so easy to read when you need to make changes that you don’t have to go through it multiple times to make the required changes.
rty32 2y ago
So we are just talking about the "WTF per minute" metric: https://commadot.com/wtf-per-minute/ https://commadot.com/wtf-per-minute/
SatvikBeri 2y ago
Recently I was going through the codebase that our company has spent the last 7 years developing, trying to find examples of code we reuse a lot. This turned out to be very unintuitive: the functions we actually reused the most had practically fallen below the threshold of conscious thought. They almost "just work", so I hadn't realized how much I'd been using them.
ziggy_star 2y ago
[dead]
- ck45 2y ago
  It was originally invented by Donald Knuth in 1984. He created Web (not the World Wide Web) for this purpose. See e.g. http://www.literateprogramming.com/ http://www.literateprogramming.com/
  - Izkata 2y ago
    What GP is referring to isn't literate programming. It's more like doc comments moved to the side instead of inline. Not sure it ever had its own name.
jeremywho 2y ago
I agree. Clever abstractions are often the antithesis of this.
stuckinhell 2y ago
That is a bold statement. I'm 100 convinced that it's based on your code architecture. 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.
v3ss0n 2y ago
That doesn't make sense . A good quality code is ready a lot, internally we reference good code as example for new employees and it is also being read, reused again and again. The author looks like just non-engineer manager. The bad code is read a few times and refactor as soon as we get a chance.
zodiac9936 2y ago
At a minimum, new code should be ready more than it is written. It's written once, then reviewed by the author and by one or more peers on your team. 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.
aaronbrethorst 2y ago
This feels borderline tautological: good code is good because it’s good. 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.
- ModernMech 2y ago
  It's because they are using "read" to mean "understood/interpreted" in the sense that the reader is executing the program in their head. In their last paragraph: It should be so well-structured and named that its purpose and functionality are immediately apparent [when read]. This minimizes the need for others to read through **and interpret** the code, allowing them to use it more effectively. (emphasis added) So the point is really: "Good code should be so apparent that when the reader reads it they do not have to be a human interpreter."
  - Sakos 2y ago
    Is that possible? I'm not sure if I've ever read code like that before, but maybe that's just me.
- bayindirh 2y ago
  Have you ever had the need to read the source code of a tool because it doesn't behave the way it should, and its help and documentation prescribes? I have been there a couple of times, and how some stuff is handled in these codebases were sad. Sloppy, assumption ridden, or pure, inelegant and fragile hacks. Even if you're reading a code to modify it, good code is easier to follow and read (point of the junior developer), and as a result, you touch less and less parts of the code to develop it even further. So yes, Good code is rarely read, or "read less, and in more niche cases".
  - gravypod 2y ago
    > Have you ever had the need to read the source code of a tool because it doesn't behave the way it should, and its help and documentation prescribes? I believe this varies wildly programmer to programmer. I'm often diving into code and reading that when debugging. I've done this with many code bases. It may be debatable if any of them are "good".
strnisa 2y ago
In the real world, code is read often and for many reasons. The main ones I can think of are: 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.
- jongjong 2y ago
  I agree with the first one but the other 2 are basically what the author is speaking out against. Some change/rework is unavoidable, but if code is good, then it should be relatively rare. Modularity isn't sufficient for code to be good. It's difficult to have truly 'loose coupling' without 'high cohesion'; each module should have distinct and well-defined responsibilities. My test for high cohesion is the question: "Is this module easy to describe to a user with limited technical abilities?" If modules are both loosely coupled and high cohesion, you'll find that you rarely need to change the code, or won't need to change it much, even after substantial refactorings. This is because such modules provide a near-optimal level of abstraction. Interfaces of such modules tend to be simple (a relatively small number of simple parameters, e.g. primitive types); this is what makes the modules easy to substitute. For example, consider a database client library, the most powerful method is for running queries against the database; this method typically requires only a single argument as a query; a string, though it will also typically support an object/map as second argument to substitute values into the query. How often do you need to change the database client library because of a refactoring? You could literally pivot your entire business model from a social media app to an enterprise CRM and you wouldn't have to change a single line of code in your database client. You might change how you use your database client within your back end logic, but you won't have to change the implementation of the client itself. There are many less extreme examples though where a module can handle very significant changes to your business without having to be modified at all. Maybe your business pivoted from being a professional/business social media app to being focused on friends and family; it might change some aspects like friend discovery, algorithm recommendations, banning, etc... But you should be able to keep most of your existing code if your code is good quality. My definition of good code is "Code that is resistant to change when faced with requirement changes." Though there is a lot of overlap with "Code that is rarely read."
sgbeal 2y ago
> In conclusion, good code is rarely read. 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).
- protomolecule 2y ago
  But is it good?
  - jacksnipe 2y ago
    It's generally held up as the standard codebase that you can go read to learn how to write "good C", so community consensus appears to be yes.
- drewcoo 2y ago
  The assertion was "good code is rarely read." good code ⇒ rarely read In that context, "often-read code" does not tell us anything about code quality. And often-read code that's not bad is not a defeater.
  - mekoka 2y ago
    On the contrary. A = "good code"; B = "rarely read"; C = "often read" A implies B B is exclusive with C X leading to C implies X is not A
    - Izkata 2y ago
      Btw this is called "contrapositive"
cess11 2y ago
So code that gets read a lot isn't good code, got it. 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.
WillAdams 2y ago
There is an entire discipline on the idea that the effort to make code easily read/understood will result in source code which is easier to maintain and write: https://literateprogramming.com/ https://literateprogramming.com/ (or if that's off-line, see: https://en.wikipedia.org/wiki/Literate_programming 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?ref=nav_mybooks&shelf=literateprograms https://www.goodreads.com/review/list/21394355-william-adams...
- lelandfe 2y ago
  Mind the s: http://literateprogramming.com/ http://literateprogramming.com/
EugeneOZ 2y ago
The person you interviewed gave a better definition. “Code that is easy to read” is often a good code. Code that is rarely read only exists in the manager’s imagination.
rodelrod 2y ago
This is only (theoretically) true in the sense that if you build the perfect abstraction, you should not have to think too often about it. 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.
treespace8 2y ago
I have found that what developers consider easy to read varies. So unless you have a lead developer with the political clout to enforce a standard you will end up with a code base with a very inconsistent style. Unfortunately in the corporate world the people with the required clout rarely want to spend the time necessary to enforce a style.
parasti 2y ago
The best code that I've worked with is always code that is easy to modify. Code that I read rarely could be anything; I'm really oblivious to how good or bad it is until I need to modify it.
wglb 2y ago
As someone who has professionally read code, I don’t think a lot of code gets read very often. It could be also that good code doesn’t take long to read. Also about the claim that that 10x programmers are fantasy, I call your attention to Fabrice Bellard https://bellard.org/ 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.
- Izkata 2y ago
  In the original context, 1 was worst, not average. Also it was a within-team ranking, not of-all-programmers.
shinzui 2y ago
The premise of the article is flawed. I read a lot of code, and that's how I learn and discover new things.
rmah 2y ago
Those who are disagreeing with the author seem to not realize that he's just engaging in a bit of navel-gazing wordplay. Sort of like when people say "good programmers should be lazy". What they really mean is that good programmers should think ahead and craft their code with an eye minimizing future modifications. 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.
- CodeMage 2y ago
  The corollary of the author's argument would be that no C++ code is good ;)
- AtlasBarfed 2y ago
  It is not good to use the word good for serious discussion of any topic. It's morning, and I really hope I did successfully pull off something close to real irony there.
  - karmakurtisaani 2y ago
    Something almost like straight out of a Garth Marenghi novel. Now go have that coffee.
- rodelrod 2y ago
  Basically he's saying that if the API is great you rarely need to read the implementation. To which: sure, in some blessed cases where the API was great to start with and nothing changed so you don't need to change the API or the implementation.
- madsbuch 2y ago
  I think the critics (myself included) perfectly understood that point. > What they really mean is that good programmers should think ahead and craft their code with an eye minimizing future modifications. The critique is exactly that this can not happen in real world projects because you can only speculate what requirements for the code base is down the road. To counter this I usually apply two princinples: 1. Occam's razor - implement the simplest solution 2. Write code that is readable and understandable, so it is easier to change the code with the requirements. The last being completely opposite to what the author of the article thinks. The worst thing I can think of is somebody needlessly DRYing up a code base prematurely - this is in my opinion a junior behavior.
SuaveSteve 2y ago
Perhaps another reason for good code being hardly read is that good code doesn't break anything.
deleted 2y ago
[deleted]
angarg12 2y ago
Code quality and how often it is read are mostly orthogonal. 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).
tetha 2y ago
Hm, I would agree more with the overall headline and conclusion if it was about time spent reading code. 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.
lsaferite 2y ago
> Good code is so ergonomic that you almost don’t need to read it; you just use it. 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.
preommr 2y ago
Genuinely, one of the worst think pieces I've seen this year. 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.
mekoka 2y ago
So, according to the author, if I write an ugly script that works very well and offers such a clean and intuitive API, that nobody needs to actually peruse the nightmare hiding within, this is good code. But only for as long as the specs don't change, or no one needs to modify my script. At which point, my good code can become bad code, by virtue of it being unintelligible. 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).
minhducck 2y ago
But how do you know that code do what it is pretend to do without reading it. The article make me think over trusted the other
IvyMike 2y ago
Is good code never altered or extended? Can good code serve as a learning tool? Can good code explain a complicated process in precise detail?
- frapaconi 2y ago
  [flagged]
stephc_int13 2y ago
This is only partially true, and not relevant in most cases. 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.
- Jensson 2y ago
  > the notion of a static codebase is largely a myth They are called game engines or physics engines etc. Everyone works with a ton of very well made code every day, you just don't think much about those since they don't cause problems.
slippy 2y ago
That's all well and good, but I don't endeavor to write good code; I endeavor to write great code!
jiggawatts 2y ago
There’s a sad corollary to this: because good code doesn’t need to be read as often, people read bad code more and internalise its bad habits. 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.
bilbo-b-baggins 2y ago
[flagged]
- deleted 2y ago
  [deleted]
abeppu 2y ago
This made me think of two tangentially related things about code quality and reading which are each 10 years old! 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/ 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-eyes/ 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.
hun3 2y ago
I think the author actually meant "Good code is rarely read twice."
simonblack 2y ago
If I am writing code that is unusually complex or going to be hard to understand for the people who read it later (usually me!), I often add extra lines 'to show my working' as well as comments. Sometimes I add those extra lines just to have something to anchor those comments on to. 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.
saghm 2y ago
While I don't disagree with the premise that code that is better needs to get read less often, I think the problem is that by the metric of "how often will this code need to be read", pretty much no one writes code good enough to not have to worry about readability. I'd argue that both buggy code _and_ unreadable code is attributable more precisely to people overestimating how good their code is rather than not trying hard enough to make their code good. > 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.
lolive 2y ago
I don’t know if we are talking here about good code vs good abstraction. For example, I have used HashMap or ExecutorService in Java extensively. And discovered years after all the internals of them. The are worlds by themselves. That you can safely keep hidden and simply use.
hamilyon2 2y ago
Reading some codebase is nobody's first choice. It is something you reach for in a pinch. 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.

104 points by alexmolas 2y ago

m463 2y ago

I was kind of wondering. Can bad code be rarely read? Or can easy to read code be bad? (also couldn't help but think "this is not the code you're looking for. move along.")

davydm 2y ago

I don't think the author has worked on long-lived projects. Eventually, all code is revisited because there's always shit to get done.

bena 2y ago
Not just long-lived projects. Working on bespoke, internal systems means you’re never truly done. And what you’ve done a month ago may not be what’s wanted now.
madsbuch 2y ago
Exactly my thoughts. The reason why good code is code that is easy to read, is because products evolve, and so does the code. Suddenly the taxonomy of that enum starts to shift, and the name that was perfect yesterday does not make sense tomorrow. These changes happen gradually and a basic acceptance of the code base not being on par with the product understanding is necessary in order to have any kind of velocity on not only spend time refactoring.
- m463 2y ago
  I disagree. "good code is easy to read" - that does not work. I can write a bubble sort instead of quicksort and that code will be bad. Maybe you can do the same thing with privacy policies. Most complicated privacy policies are bad, so they make them hard to read so that people do NOT understand them and give up. But you could have a privacy policy that is bad and easy to read. "We can do anything". I think good code is primarily easy to read. And I think it should not attract attention through bad behavior, so it should additionally not come under scrutiny for that.
  - madsbuch 2y ago
    Of course your code should live up to requirements and be correct, for it to be good - The requirements can also be performance requirements. If you have a list of maximally 10 elements that needs to be sorted and you opt for quicksort over bubble sort in a context where bubble sorts time/space guarantees perfectly solved the requirements, well, then you absolutely wrote bad code. This is what a more senior developer understands, where a junior would jump in and write worse code.
jeremywho 2y ago
I don’t think you read the whole article. I had the same thought as you from the headline, but they gone on to state that good code is so easy to read when you need to make changes that you don’t have to go through it multiple times to make the required changes.
chaboud 2y ago
I had a similar reaction while reading this, something along the lines of “well, that’s a bunch of idealistic tripe”. And, honestly, I think that somewhat holds. That said, as an aim, writing readable code that doesn’t need to be read to be used is a good one. I wrote as much in a quora response almost a decade ago to the question “how does one become a great coder” ( https://www.quora.com/How-does-one-become-a-great-coder-programmer/answer/Matthew-Chaboud?ch=15&oid=12759472&share=5db82526&srid=vWzg&target_type=answer https://www.quora.com/How-does-one-become-a-great-coder-prog... ), and I think it still holds. However, the other part of that answer was to make the code immensely readable, because we read more code than we write unless we’re incredibly junior or comically superhuman.
wglb 2y ago
I did a consulting gig at Allstate around the time of Y2K. I chatted with a senior architect who had been with the company for over 20 years. He noted that there were such a vast array of programs and systems in place, some of which had been running for at least 40 years. I wonder if any of that code had been read, good or bad, for decades. And I am willing to bet that the source code for some of it was lost. This of course led to no small level of anxiety during the run up to Y2K. As a side note, while I was there, the dictum came down that there was to be no more assembler programming to be done. I know what you are thinking. They should just burn the mainframe with fire and rewrite it all. I recommend the book https://www.amazon.com/Kill-Fire-Manage-Computer-Systems/dp/1718501188 https://www.amazon.com/Kill-Fire-Manage-Computer-Systems/dp/....
drewcoo 2y ago
The long-lived projects I've seen have some code that mostly works that doesn't have any tests and is hard to grok. Nobody touches it because 1) any change might break something unexpected and 2) if you touch it, you might end up owning it. I wouldn't call that good code but it's often too good to spend time replacing.
weebull 2y ago
There's a class of code where you never need to read it because it's effect is well understood and it does it without problems. It has the right level of abstraction to be useful in multiple places and not specific to a singular case. It's not going to be top level code, but it's a building block you know you can rely on. This is something I think functional styles of programming lead more naturally towards than OO or procedural. It's far easier to separate concerns when you can pass around like bundles of functionality (i e. first order functions). Also it really helps when you are used to writing code with no dependency except what is passed in, and not effect except what is returned. Then thhen you're sure that the code is not leaky in it's abstraction. You can do it in other paradigms, but it's it's not where the language naturally leads you. OO has retained state as a key foundation of it's philosophy. Procedural code tends to mix up the how something is done and the what is being done. (e.g. the iteration through a data structure, with the definition of what is being searched for).
- deleted 2y ago
  [deleted]

bena 2y ago

I don’t think this is a good rule of thumb. 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.

jeremywho 2y ago
I don’t think you read the whole article. I had the same thought as you from the headline, but they gone on to state that good code is so easy to read when you need to make changes that you don’t have to go through it multiple times to make the required changes.

rty32 2y ago

So we are just talking about the "WTF per minute" metric: https://commadot.com/wtf-per-minute/ https://commadot.com/wtf-per-minute/

SatvikBeri 2y ago

Recently I was going through the codebase that our company has spent the last 7 years developing, trying to find examples of code we reuse a lot. This turned out to be very unintuitive: the functions we actually reused the most had practically fallen below the threshold of conscious thought. They almost "just work", so I hadn't realized how much I'd been using them.

ziggy_star 2y ago

[dead]

ck45 2y ago
It was originally invented by Donald Knuth in 1984. He created Web (not the World Wide Web) for this purpose. See e.g. http://www.literateprogramming.com/ http://www.literateprogramming.com/
- Izkata 2y ago
  What GP is referring to isn't literate programming. It's more like doc comments moved to the side instead of inline. Not sure it ever had its own name.

jeremywho 2y ago

I agree. Clever abstractions are often the antithesis of this.

stuckinhell 2y ago

That is a bold statement. I'm 100 convinced that it's based on your code architecture. 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.

v3ss0n 2y ago

That doesn't make sense . A good quality code is ready a lot, internally we reference good code as example for new employees and it is also being read, reused again and again. The author looks like just non-engineer manager. The bad code is read a few times and refactor as soon as we get a chance.

zodiac9936 2y ago

At a minimum, new code should be ready more than it is written. It's written once, then reviewed by the author and by one or more peers on your team. 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.

aaronbrethorst 2y ago

This feels borderline tautological: good code is good because it’s good. 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.

ModernMech 2y ago
It's because they are using "read" to mean "understood/interpreted" in the sense that the reader is executing the program in their head. In their last paragraph: It should be so well-structured and named that its purpose and functionality are immediately apparent [when read]. This minimizes the need for others to read through **and interpret** the code, allowing them to use it more effectively. (emphasis added) So the point is really: "Good code should be so apparent that when the reader reads it they do not have to be a human interpreter."
- Sakos 2y ago
  Is that possible? I'm not sure if I've ever read code like that before, but maybe that's just me.
bayindirh 2y ago
Have you ever had the need to read the source code of a tool because it doesn't behave the way it should, and its help and documentation prescribes? I have been there a couple of times, and how some stuff is handled in these codebases were sad. Sloppy, assumption ridden, or pure, inelegant and fragile hacks. Even if you're reading a code to modify it, good code is easier to follow and read (point of the junior developer), and as a result, you touch less and less parts of the code to develop it even further. So yes, Good code is rarely read, or "read less, and in more niche cases".
- gravypod 2y ago
  > Have you ever had the need to read the source code of a tool because it doesn't behave the way it should, and its help and documentation prescribes? I believe this varies wildly programmer to programmer. I'm often diving into code and reading that when debugging. I've done this with many code bases. It may be debatable if any of them are "good".

strnisa 2y ago

In the real world, code is read often and for many reasons. The main ones I can think of are: 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.

jongjong 2y ago
I agree with the first one but the other 2 are basically what the author is speaking out against. Some change/rework is unavoidable, but if code is good, then it should be relatively rare. Modularity isn't sufficient for code to be good. It's difficult to have truly 'loose coupling' without 'high cohesion'; each module should have distinct and well-defined responsibilities. My test for high cohesion is the question: "Is this module easy to describe to a user with limited technical abilities?" If modules are both loosely coupled and high cohesion, you'll find that you rarely need to change the code, or won't need to change it much, even after substantial refactorings. This is because such modules provide a near-optimal level of abstraction. Interfaces of such modules tend to be simple (a relatively small number of simple parameters, e.g. primitive types); this is what makes the modules easy to substitute. For example, consider a database client library, the most powerful method is for running queries against the database; this method typically requires only a single argument as a query; a string, though it will also typically support an object/map as second argument to substitute values into the query. How often do you need to change the database client library because of a refactoring? You could literally pivot your entire business model from a social media app to an enterprise CRM and you wouldn't have to change a single line of code in your database client. You might change how you use your database client within your back end logic, but you won't have to change the implementation of the client itself. There are many less extreme examples though where a module can handle very significant changes to your business without having to be modified at all. Maybe your business pivoted from being a professional/business social media app to being focused on friends and family; it might change some aspects like friend discovery, algorithm recommendations, banning, etc... But you should be able to keep most of your existing code if your code is good quality. My definition of good code is "Code that is resistant to change when faced with requirement changes." Though there is a lot of overlap with "Code that is rarely read."

sgbeal 2y ago

> In conclusion, good code is rarely read. 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).

protomolecule 2y ago
But is it good?
- jacksnipe 2y ago
  It's generally held up as the standard codebase that you can go read to learn how to write "good C", so community consensus appears to be yes.
drewcoo 2y ago
The assertion was "good code is rarely read." good code ⇒ rarely read In that context, "often-read code" does not tell us anything about code quality. And often-read code that's not bad is not a defeater.
- mekoka 2y ago
  On the contrary. A = "good code"; B = "rarely read"; C = "often read" A implies B B is exclusive with C X leading to C implies X is not A
  - Izkata 2y ago
    Btw this is called "contrapositive"

cess11 2y ago

So code that gets read a lot isn't good code, got it. 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.

WillAdams 2y ago

There is an entire discipline on the idea that the effort to make code easily read/understood will result in source code which is easier to maintain and write: https://literateprogramming.com/ https://literateprogramming.com/ (or if that's off-line, see: https://en.wikipedia.org/wiki/Literate_programming 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?ref=nav_mybooks&shelf=literateprograms https://www.goodreads.com/review/list/21394355-william-adams...

lelandfe 2y ago
Mind the s: http://literateprogramming.com/ http://literateprogramming.com/

EugeneOZ 2y ago

The person you interviewed gave a better definition. “Code that is easy to read” is often a good code. Code that is rarely read only exists in the manager’s imagination.

rodelrod 2y ago

This is only (theoretically) true in the sense that if you build the perfect abstraction, you should not have to think too often about it. 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.

treespace8 2y ago

I have found that what developers consider easy to read varies. So unless you have a lead developer with the political clout to enforce a standard you will end up with a code base with a very inconsistent style. Unfortunately in the corporate world the people with the required clout rarely want to spend the time necessary to enforce a style.

parasti 2y ago

The best code that I've worked with is always code that is easy to modify. Code that I read rarely could be anything; I'm really oblivious to how good or bad it is until I need to modify it.

wglb 2y ago

As someone who has professionally read code, I don’t think a lot of code gets read very often. It could be also that good code doesn’t take long to read. Also about the claim that that 10x programmers are fantasy, I call your attention to Fabrice Bellard https://bellard.org/ 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.

Izkata 2y ago
In the original context, 1 was worst, not average. Also it was a within-team ranking, not of-all-programmers.

shinzui 2y ago

The premise of the article is flawed. I read a lot of code, and that's how I learn and discover new things.

rmah 2y ago

Those who are disagreeing with the author seem to not realize that he's just engaging in a bit of navel-gazing wordplay. Sort of like when people say "good programmers should be lazy". What they really mean is that good programmers should think ahead and craft their code with an eye minimizing future modifications. 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.

CodeMage 2y ago
The corollary of the author's argument would be that no C++ code is good ;)
AtlasBarfed 2y ago
It is not good to use the word good for serious discussion of any topic. It's morning, and I really hope I did successfully pull off something close to real irony there.
- karmakurtisaani 2y ago
  Something almost like straight out of a Garth Marenghi novel. Now go have that coffee.
rodelrod 2y ago
Basically he's saying that if the API is great you rarely need to read the implementation. To which: sure, in some blessed cases where the API was great to start with and nothing changed so you don't need to change the API or the implementation.
madsbuch 2y ago
I think the critics (myself included) perfectly understood that point. > What they really mean is that good programmers should think ahead and craft their code with an eye minimizing future modifications. The critique is exactly that this can not happen in real world projects because you can only speculate what requirements for the code base is down the road. To counter this I usually apply two princinples: 1. Occam's razor - implement the simplest solution 2. Write code that is readable and understandable, so it is easier to change the code with the requirements. The last being completely opposite to what the author of the article thinks. The worst thing I can think of is somebody needlessly DRYing up a code base prematurely - this is in my opinion a junior behavior.

SuaveSteve 2y ago

Perhaps another reason for good code being hardly read is that good code doesn't break anything.

deleted 2y ago

[deleted]

angarg12 2y ago

Code quality and how often it is read are mostly orthogonal. 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).

tetha 2y ago

Hm, I would agree more with the overall headline and conclusion if it was about time spent reading code. 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.

lsaferite 2y ago

> Good code is so ergonomic that you almost don’t need to read it; you just use it. 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.

preommr 2y ago

Genuinely, one of the worst think pieces I've seen this year. 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.

mekoka 2y ago

So, according to the author, if I write an ugly script that works very well and offers such a clean and intuitive API, that nobody needs to actually peruse the nightmare hiding within, this is good code. But only for as long as the specs don't change, or no one needs to modify my script. At which point, my good code can become bad code, by virtue of it being unintelligible. 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).

minhducck 2y ago

But how do you know that code do what it is pretend to do without reading it. The article make me think over trusted the other

IvyMike 2y ago

Is good code never altered or extended? Can good code serve as a learning tool? Can good code explain a complicated process in precise detail?

frapaconi 2y ago
[flagged]

stephc_int13 2y ago

This is only partially true, and not relevant in most cases. 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.

Jensson 2y ago
> the notion of a static codebase is largely a myth They are called game engines or physics engines etc. Everyone works with a ton of very well made code every day, you just don't think much about those since they don't cause problems.

slippy 2y ago

That's all well and good, but I don't endeavor to write good code; I endeavor to write great code!

jiggawatts 2y ago

There’s a sad corollary to this: because good code doesn’t need to be read as often, people read bad code more and internalise its bad habits. 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.

bilbo-b-baggins 2y ago

[flagged]

deleted 2y ago
[deleted]

abeppu 2y ago

This made me think of two tangentially related things about code quality and reading which are each 10 years old! 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/ 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-eyes/ 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.

hun3 2y ago

I think the author actually meant "Good code is rarely read twice."

simonblack 2y ago

If I am writing code that is unusually complex or going to be hard to understand for the people who read it later (usually me!), I often add extra lines 'to show my working' as well as comments. Sometimes I add those extra lines just to have something to anchor those comments on to. 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.

saghm 2y ago

While I don't disagree with the premise that code that is better needs to get read less often, I think the problem is that by the metric of "how often will this code need to be read", pretty much no one writes code good enough to not have to worry about readability. I'd argue that both buggy code _and_ unreadable code is attributable more precisely to people overestimating how good their code is rather than not trying hard enough to make their code good. > 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.

lolive 2y ago

I don’t know if we are talking here about good code vs good abstraction. For example, I have used HashMap or ExecutorService in Java extensively. And discovered years after all the internals of them. The are worlds by themselves. That you can safely keep hidden and simply use.

hamilyon2 2y ago

Reading some codebase is nobody's first choice. It is something you reach for in a pinch. 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.