Code Should be Readable

First published on
On the first day of my first job, at age 23, I learned the most important lesson of my life about programming: code should be readable. Four years of CS at university did not prepare me for this, but one day of work did (thanks Achiel!).

I had created something "clever" and was barked at by the Senior Engineer of the team that my solution was too complicated. For a second I thought he was suffering from low IQ, but he explained that:

  1. He was not able to instantly understand my code. Lesson: It was apparently vital that other people in the team understood my code. In fact, it was not even my code, the team owned it.
  2. The problem I was solving was simple and not worth spending much mental capacity on. Lesson: writing code is just a small part of what happens with it, code is much more frequently read, tested, debugged and refactored. All these activities take time and mental capacity.
  3. In 6 months, I would have forgotten the code and would look at it the same way he did now (that is: with a frown and raised eyebrows). Lesson: You are temporarily suffering from understanding the code too well, make sure you compensate for that.
  4. We were paid (quite well) to make product for the company, not to be smart-asses. Lesson: time is money and there is something called Opportunity Cost that makes your time even more valuable. Boring code is good code.
These lessons have stuck with me forever and made me allergic to complicated code. Of course sometimes problems really are complex, and there is big difference between "essential complexity" and "merely complicated". Senior Software Engineers should have a well-developed gut feeling to distinguish between the two.

I don't care much for fanatic discussions about Test Driven Development or Micro Services vs. Monoliths because reality is much less clear-cut. I think it's MUCH more important that whenever you create software, or basically anything*, that you keep this in mind:
  • the complexity of the solution should match the complexity of the problem
  • what you create should be easy to understand for those who work with it

As long as you build your software by these two rules, you should be alright.




* read The Design of Everyday things by Don Norman and Don't Make me Think by Steve Krug

Popular posts from this blog

AI programming tools should be added to the Joel Test

First published on
Here's a wake-up call to all CTOs: AI programming tools are getting freaking amazing and if you don't allow your teams to use them somehow, it will bite you in the ass in a couple of years. You will be slower and you will lose your best people. The infamous Joel Test is a list from the year 2000 of 12 things all great software companies do. Since then most companies have implemented Git and CI/CD, checking of three items, so we have some space left in the 2024 update ;) I believe "Do you allow your developers to use AI assisted development environments?" is a necessary addition. I get that you don't want your source code to end up on some OpenAI / Microsoft / Github server somewhere, sure, but find a way to use your own models or learn to live with it. Note that this is often not the same as "#9 - Do you use the best tools money can buy?" as blocking AI tools is about data security, not money. So why do I think developers need AI programming tools? I&#
Read more

The unreasonable effectiveness of i3, or: ten years of a boring desktop environment

First published on
Image
My wife uses Windows and over the years I've helped her move things to new systems. Win8, 10 and now 11. With every change the UI changes. Now I can't right click the bottom right corner anymore to open Task Manager. The UI feels "fresh" and up-to-date I guess, but does it really matter? My desktop has looked like this since 2008. I love the picture of the gearbox, it's a testament to the hidden precision engineering that goes on inside the built world all the time. I don't see much of the gearbox though, because most of the time my screens look like this: The environment around my background picture has changed a little more, but has been stable for the last 10 years. My experience is very different to my wife's constantly changing system. In 2009 I moved from Windows to Ubuntu, then to Debian using Gnome. Then finally to i3 in 2013 after a brief affair with XMonad in 2012. So by now in early 2024, I've had the same minimal UI for more than 10 years,
Read more

Idea time: RFID+E-Ink, electronic price tags without batteries

First published on
I got this idea years ago, somewhere in 2004 after I had heard both of RFID and E-Ink. The order is irrelevant ;) The idea is simple, we take: 1) RFID readers, which send radio waves to tags, which pick up some of the energy in the wave, do some computations and send a reply. The tags are brilliant: no batteries, no connected power source of any kind except for the antenna. 2) E-Ink displays, which need power only to change pixels. After the power is cut off, the pixels remain in their current state. The result: a small tag with a display. The display gets initialised and updated by an RFID-reader and after that retains its state indefinitely. Perfect for price tags on shelves in supermarkets, which need to be updated every now and then but are hellish to replace. I soon found out in 2004 that Epson had already done this:  http://gizmodo.com/026090/epsons-electronic-ink-%252B-rfid--21st-century-price-tags
Read more