The single worst thing anyone can say to me is, “Your code’s clever”. Immediate red flag. Alarm bells. I start questioning my life and the decisions I made that led me to that point.
The absolute best code that you can interact with is code you delete. Deleting code is extremely hard to do. Maintaining less code means fewer things that can go wrong. It increases resources (above all developer time) available to your organization.
The second best code you can interact with is code you avoid writing. This is also hard to do. This means serving customer needs with existing feature sets or figuring out pragmatic workarounds. Not writing code maintains your organization’s resources.
The third best code you can interact with is code you write that no one thinks about. This is “boring”, “simple”, or “dumb” code. It’s hard to write code like this! This requires having a keen sense of empathy for one’s readers and having been taught how to write simple code. This code slightly decreases resources available to your organization in that it’s additional knowledge that a developer needs to keep in their head, and it’s another thing that can go wrong.
The worst code is code that your team has to think about during any part of the software’s lifecycle. This code can be “confusing”, but often it’s “clever”.
Clever code is code where form obscures function. Sometimes “clever” is in pursuit of concision: that nested list comprehension that packs five operations into one line. Sometimes, it’s excitement about language features or behaviors that lie outside of team conventions. Sometimes, it’s reliance on implicit side-effects. If a competent college hire – broadly familiar with your language, service, and domain – can’t tell you what a piece of code is doing and how after being left alone with it for five minutes, it’s probably clever.
Clever code is not hard-earned optimized code, well-documented and hidden behind a simple interface. It’s also not code with extremely high levels of inherent complexity – anything that’s basically just math or transcriptions of scientific papers. In these cases form does not obscure function, rather the function itself is complex.
It’s fun to write clever code. “Ah”, we think, “Here is the time that I finally get to make use of metaclasses”. Or, “I bet I can make this even shorter.” Clever code that makes use of side effects is easy to write. It’s natural to forget that others, years later won’t have your mental view that allows for shortcuts. You have unobstructed vision; your readers are staring through a narrow cardboard tube.
Both “confusing” and “clever” mean that someone worked to understand it. This includes during review. I guarantee that if a reviewer worked to understand it then, they’ll work even harder to understand it, bleary-eyed at 3am under the stress of a blaring pager. Given that they worked to understand it, I’m not confident that they fully understood it. Or that the next person, who doesn’t have the benefit of the author’s presence will fully understand it and will be able to modify the code in ways that avoid subtle errors. This is all to say: clever code greatly decreases resources available to your organization.
Clever code is insidious. It makes engineers stifle confusion out of fear of looking dumb. Do not make the mistake of confounding burden on the reader with skill or “intelligence” of the writer. Skillful, high-effort artifacts do not give the appearance of intelligence. They look “dumb”. They look like “why are we even talking about this?”. They look like “Gah, okay, we don’t have better options and that’s good enough”.
The reviewer’s antidote to cleverness is relentless and vocal stupidity. Say something every time you’re confused. Refuse to be intimidated by artifacts that look “smart” and have you questioning your competencies. Help your colleagues empathize with their readers by explaining the context the reader has and lacks. Ask yourself, “Do I expect new team members to understand this quickly?”. Ask yourself, “Can this be simpler?”. Ask yourself, “Am I not asking questions or objecting out of fear of looking dumb?”.
The reviewee’s antidote to cleverness is threefold.
First is empathy. We’re all familiar with the process of reading code and imagining in our heads how that code plays out for a computer – the state of the executed program at any moment in time. Likewise, get in the habit of imagining how code plays out for your reader. How is it held in their head at any moment? How can you make it “execute” more easily, removing points of friction, anticipating objections, adding comments for irreducible complexity? Ask yourself, “Can I expect a college hire to understand this in less than five minutes?”.
The second antidote is to sacrifice all ego. Be intensely skeptical of any change that makes you feel smart. This is hard! School trains us to get that dopamine hit from understanding and reproducing the obscure. This means rewiring your brain to get satisfaction out of doing “non-impressive” work. Ask yourself, “What am I proud of, that makes me feel smart, that I can delete?”.
The third is that of relentless simplicity. Every step of the way ask yourself, “What bad thing will happen if I delete this?”. Ask yourself, “How can I make this simpler?”. Be ruthless.
Coming full circle, we can’t always delete code or get away without writing code. We’re hired, in part, to produce artifacts. When producing artifacts, however, it pays to be intensely aware of the risk to which you’re exposing your future self, your colleagues, and your organization. That of bugs, of oncall burden, of a landmine of a codebase which can’t be safely changed, of reduced velocity, of unhappy customers, etc. I can’t guarantee that simple, dumb artifacts – be they designs or implementations – will eliminate risk. I can, however, say with absolute certainty that clever artifacts, especially compounded, will result in unmaintainable pain.
Demand better. Look stupid. Avoid clever.