Code design
Designing efficient code is an art and sometimes is required to have knowledge from multiple fields in order to make it easy to understand and also fast. Here I resume knowledge acquired during some years working with it.
For me the best code is the one that is easy to use, and not complex. Meaning that the developer will not have a big cognitive load when trying to develop a new feature or extend some functionality. The code reflects, when written, tree types of thing:
- The interpretation of the writer about the problem;
- The writers ability to make abstractions;
- The writers understanding and manipulation of the language that he is using.
But once written the code serves as a language from the writer to the computer and from the writer to the future self. As the time passes our interpretation of the problems that we are trying to solve, mental models and knowledge about the language evolves and so we can find better ways to write it, meaning that it is probable that we will end up with technical debt.
I really like the book Ousterhout, John in A Philosophy of Software Design [[202102191934-APhilosophyofSoftwareDesign]], my visions align with his and accordingly with him the complexity can present itself in tree forms:
- Change amplification: When you are trying to change one thing and end up having to rewrite the software;
- Cognitive load: When you spend too much time trying to understand the code, before being able to change it;
- Unknown unknowns: When the dependencies and behavior isn't clear in some part of the code.
So to reduce the rate that we generate technical debt we can follow some principles that will help us in the future, the first one is to hide complexity. We need to design interfaces that are easy to use and that are deep, allowing the user to not think about what is underneath the interface and only worrying with how to use it. we can help the user by making the default use case as easy as possible.
The second point is consistency, when we follow some pattern we gain cognitive leverage, and this can have effects on productivity because we know how things are supposed to be done and catch some errors when we unadvertised change the order of the things.
The third is documentation, here I note tree types of it:
- The structure: the way the code is implemented is a form of documentation, because it encodes how the problem is solved;
- The naming of the variable/functions or classes: this is important because makes the context easy to understand;
- Comments: Besides the description of the variables and functions, comments are important to encode the thought process of the writer, that otherwise couldn't be represented in code.
The forth point is to handle possible errors as they appear. The best way to do this is to rewrite the code in a form that they can't bother the user of the code, if this is not possible, at least describe the error on the definition documentation of the function.
Remember the fact that simple is not necessarily easy.
Code patterns
One way of reducing complexity and making the interface simpler is using code patterns they appear in many problems and its up to the developer identify when its usage is applicable.[[code_patterns]]