Understandable Code

Last week I had a chat with my colleague Suzi. She wanted me to review a small change she made on a software almost entirely written by me. At some point she came out with this:

[Another colleague] always says you are too smart, and we just lose our mind when we read your code

Damn! This is the certification of my failure! I always try to make my code understandable but it seems that my effort has not been enough, at least in this case.

On the other hand, that program regulates a process that has many small details to consider and if you don't know them, you cannot understand the code. In addition, I've had to implement some heavy optimizations and this reduces the readability even more.

Curiously, during the past two weeks, I've worked on a small (less than 1000 lines) program that suffers the same issue. It is complicated. It is complicated because the operations it has to do are complicated.

No matter the names of variables and functions. No matter how the code has been organized. No matter all the effort you can put into your job. Comments can help, but, in the end, only a deep knowledge of subject of the program lets you understand it.

Image by NY taken from The Blue Diamond Gallery licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported license.