Introduction
I was reading The Art of Unix Programming out of curiosity, and its a great document/book that brings lots of thoughts about modeling and clean interfaces design that was learnt from the creation of the Unix OS. In the Book it has many great topics and discussions, and one that stuck with me and I keep thinking about it is under Basics of the Unix Philosophy:
Rule of Clarity: Clarity is better than cleverness.
And oh boy have I tried to be clever in my code 😅. I’ve seen many times code that are clever but for me to notice that its clever it took me more than a hour to go though 20-30 lines of code. It might seem like a good code but we need to take in considerations multiple factors such as:
- Will I understand the code after a couple of months?
- How will a Junior or onboarding engineer feel when joining the team?
- What if it has a bug how can I trace down easily where its failing?
All of this questions should go through our head when writing a code, we need to remember that piece of code will probably outlive everyone tenure in the company - if you consider very old companies even outlive you 👀.
Because maintenance is so important and so expensive, write programs as if the most important communication they do is not to the computer that executes them but to the human beings who will read and maintain the source code in the future (including yourself).
- Basic of the Unix Philosophy
Write code for people not machines
We should forget about small efficiencies, say about 97% of the time: premature optimization is the root of all evil. Donald Knuth, author of The Art of Computer Programming
Have you seem some codes that are performant codes, or even competitive programming code.
// Z algorithm - This algorithm efficiently locates all instances of a specific pattern within a text in linear time
int[] genZValues(String s) {
int[] z = new int[s.length()];
for(int i=1,g=0,f=0,N=s.length(); i<N; i++)
if(i<g && z[i-f]!=g-i)
z[i] = Math.min(z[i-f],g-i);
else for(g=g>(f=i)?g:f,z[i]=g-f;g<N && s.charAt(g)==s.charAt(z[i]); g++,z[i]++);
return z;
}
They are sum of single letter variables, with crazy operations over data structures that aims for the best performance, time complexity and less surface of code. But the single face that most of people do when they see this type of code is
Although we write code for machines, people are the one that maintain, read, fix and even improve it (Devin AI) is coming for your job).* So writing performant code usually becomes quickly hard and obscure code, accessing different data structures or specific core functions of a language. And by having this complex code to maintain and build upon, delivering value becomes harder.
Never struggle to decipher subtle code three times. Once might be a one-shot fluke, but if you find yourself having to figure it out a second time — because the first was too long ago and you’ve forgotten details — it is time to comment the code so that the third time will be relatively painless.
- Henry Spencer, creator of Regex
Tests: don’t forget they need to be clear as well
So we put effort into a clear and simple code, with comments but then we want to better understand the cases and expected behavior. Then we went to the tests to find out and see:
;; Clojure test
(testing "Function Logic Test"
(testing "Should return expected values for arguments"
(is (= 100 (function-logic 1200 :equal "2024-07-10")))
(is (= 1000 (function-logic 1200 :distributed "2024-07-12")))
(testing "Should return nil for values not consistent"
(is (= nil (function-logic 500 :equal "2025-07-12")))
(is (= nil (function-logic 10:distributed "2000-07-12")))))
Its a random example but we’ve all seen a test like this (or even no test at all ¯*(ツ)*/¯), and test is not to prove that our new code doesn’t break but also guarantee the understanding and consistency of the code in the future. This way we should write our tests to be clear as well, understandable and specially accessible for all levels of seniority. It might be you in the future debugging your own code 1 year from now, so help yourself!
Conclusion
So sometimes we just need to be clear, it might seem like a good approach to have a clever - the dev says its little complex so its ok… - code but we don’t see many hidden pitfalls at first we don’t see. One of them I want to talk in a future post Psychological safety in a code base. One really good talk that I feel it also resonates with the topic is Simple Made Easy by Rich Hickey (creator of Clojure)