I love this. You perfectly summed up so many thoughts I have after 15 years of professional programming (including the comment about ChatGPT's code).
The best way to learn the value of simple code is to be the person who has to pick it up again... preferably in an emergency where you have to make and deploy a change very quickly, and also be confident that you're not going to take the system down.
You REALLY appreciate simple code in environments like that.
Nov 20, 2023·edited Nov 20, 2023Liked by Leonardo Creed
>when it comes to performance reviews, this code looks trivial
Ah, the not-so-palatable non-tech stuff that is needed to survive and get ahead in Big Cos. I wonder what it takes to change one's mindset from say, working forever in startups where the focus is on shipping, to moving to Big Co where one has to pay attention to these "other" things. Is it even possible?
It is very true that debugging code is twice as hard as writing it. I also liked your conclusion that you get better at writing clear code by having more experienced devs review it. I firmly believe that, in all aspects of programming, you get better at writing good code through collaboration.
While I agree that to write good code you also have to strictly follow a guide line, it's also a matter of good design. To me, how you refactor your code in files, classes, functions, plus your project structure should reflect the mental model of the problem you're trying to solve. Achieving good design in code is a matter of training your eye, iterating over solutions, plus acquiring good taste. I don't think it's trivial to figure this out at first. Collaborating with experienced devs who write elegant code is the way I believe you can build this skill.
Great read, but I'd like to add a point about linters and prettifiers.
From an article I wrote: "Having Ruff as a safety net is not an excuse to write poorly formatted code or code that makes your eyes water at first glance. If careless, linters and formatters may give developers a false sense of quality and readability. It’s important to be self-aware of this reality."
>I was shocked - this wasn’t some startup. This was one of the biggest companies in the world, known for their engineering culture.
My first interpretation is that the manager was overly concerned with optics. My second thought is that they saw the gap between the complexity of the solution and the simplicity of the code. Your spaghetti code hinted at the complexity of the solution through its complication.
The insight that your manager may have had but not shared is that complex solutions come from simple components interacting elegantly, something that a layprogrammer would not have in mind when reading the code for the first time.
Obligatory car analogy: It's like an engine builder who's honed every component to exacting tolerances of fit and finish -- to the point where it will never need a rebuild -- only to have the designer of the car it's going into ask for blueprints of the already working engine.
As Brian Kernighan wrote (in The Elements of Programming Style), “Everyone knows that debugging is twice as hard as writing a program in the first place. So if you're as clever as you can be when you write it, how will you ever debug it?”
Instead of trying to use "clear" and "readable" as milestones on the path of good/better coding or pretending that you have suddenly reached programming nirvana, perhaps it would be best to focus on the aspect of coding which is CURRENTLY considered most important.
It wasn't always this way, might not be like this again, and isn't necessarily the objective best.
The plainest way of summarizing the concept is "How well will the least intelligent programmer you work with be able to understand this code?".
I appreciate the comment, but not sure how that's different from the article's point.
"How well will the least intelligent programmer you work with be able to understand this code?" is a more verbose way of saying "How understandable is this code?". Understandable == clear == readable.
Clarity of code can't be quantified as a metric (and thus cannot be a milestone), which is why this article is an anecdotal story and not a set of rules.
A non-trivial element of my point here is that not all people are equally intelligent or capable in the department of reading and understanding/comprehending code (it's just a fact) and that there is in fact a bottom bar /somewhere/
Below that bar (whatever version) is a land where making it any more "readable" or "understandable" amounts to trading in the conception, planning, and implementation of f software for "low code" and the coding equivalent of "alphabet blocks".
Or, to be rather more blunt, something akin to hiring a bunch of /trained monkeys using typewriters/ and expecting novels that are worth reading (or writing, for that matter).
I love this. You perfectly summed up so many thoughts I have after 15 years of professional programming (including the comment about ChatGPT's code).
The best way to learn the value of simple code is to be the person who has to pick it up again... preferably in an emergency where you have to make and deploy a change very quickly, and also be confident that you're not going to take the system down.
You REALLY appreciate simple code in environments like that.
>when it comes to performance reviews, this code looks trivial
Ah, the not-so-palatable non-tech stuff that is needed to survive and get ahead in Big Cos. I wonder what it takes to change one's mindset from say, working forever in startups where the focus is on shipping, to moving to Big Co where one has to pay attention to these "other" things. Is it even possible?
Great post!
It is very true that debugging code is twice as hard as writing it. I also liked your conclusion that you get better at writing clear code by having more experienced devs review it. I firmly believe that, in all aspects of programming, you get better at writing good code through collaboration.
While I agree that to write good code you also have to strictly follow a guide line, it's also a matter of good design. To me, how you refactor your code in files, classes, functions, plus your project structure should reflect the mental model of the problem you're trying to solve. Achieving good design in code is a matter of training your eye, iterating over solutions, plus acquiring good taste. I don't think it's trivial to figure this out at first. Collaborating with experienced devs who write elegant code is the way I believe you can build this skill.
Great read, but I'd like to add a point about linters and prettifiers.
From an article I wrote: "Having Ruff as a safety net is not an excuse to write poorly formatted code or code that makes your eyes water at first glance. If careless, linters and formatters may give developers a false sense of quality and readability. It’s important to be self-aware of this reality."
Huh yeah, that's a good point
>I was shocked - this wasn’t some startup. This was one of the biggest companies in the world, known for their engineering culture.
My first interpretation is that the manager was overly concerned with optics. My second thought is that they saw the gap between the complexity of the solution and the simplicity of the code. Your spaghetti code hinted at the complexity of the solution through its complication.
The insight that your manager may have had but not shared is that complex solutions come from simple components interacting elegantly, something that a layprogrammer would not have in mind when reading the code for the first time.
Obligatory car analogy: It's like an engine builder who's honed every component to exacting tolerances of fit and finish -- to the point where it will never need a rebuild -- only to have the designer of the car it's going into ask for blueprints of the already working engine.
As Brian Kernighan wrote (in The Elements of Programming Style), “Everyone knows that debugging is twice as hard as writing a program in the first place. So if you're as clever as you can be when you write it, how will you ever debug it?”
Yeah experienced this myself at a startup; fast lean code gets it done but then maintenance is a pain!
Also I didn't realize how granular making code diffs would help; not just i separating functionality but also in the case of reverting errors :)
Great piece!
Instead of trying to use "clear" and "readable" as milestones on the path of good/better coding or pretending that you have suddenly reached programming nirvana, perhaps it would be best to focus on the aspect of coding which is CURRENTLY considered most important.
It wasn't always this way, might not be like this again, and isn't necessarily the objective best.
The plainest way of summarizing the concept is "How well will the least intelligent programmer you work with be able to understand this code?".
I appreciate the comment, but not sure how that's different from the article's point.
"How well will the least intelligent programmer you work with be able to understand this code?" is a more verbose way of saying "How understandable is this code?". Understandable == clear == readable.
Clarity of code can't be quantified as a metric (and thus cannot be a milestone), which is why this article is an anecdotal story and not a set of rules.
A non-trivial element of my point here is that not all people are equally intelligent or capable in the department of reading and understanding/comprehending code (it's just a fact) and that there is in fact a bottom bar /somewhere/
Below that bar (whatever version) is a land where making it any more "readable" or "understandable" amounts to trading in the conception, planning, and implementation of f software for "low code" and the coding equivalent of "alphabet blocks".
Or, to be rather more blunt, something akin to hiring a bunch of /trained monkeys using typewriters/ and expecting novels that are worth reading (or writing, for that matter).
So cooool 💯