Reading code is only easy in trivial systems and a system that has a lot of functionality usually has a lot of code. Reading code is a critical part of what software developers do every day so it makes sense to make reading code easier by making the code more intuitive to the largest population of programmers.
There are books and numerous articles on software design, patterns and naming conventions. I encourage everyone to read those, this blog post is not an attempt to create and exhaustive guide to writing good code. Here I am going to cover a few small hacks that help people understand what your are doing faster. The first topic of discussion is classes.
When I started programming in 1990s Object Oriented Programming (OOP) was all the rage. After 25 years I have noticed that software field has fashionable trends where “everything must be so”, so in 1990s a lot of people were into C++ and Java (today the fashionable thing is micro services). Objects and classes were not invented in the 90s but they definitely were “the way” if you wanted to write your code “the right way”.
Java took OOP to an extreme and required you to have a class for every function. This took out an important signal from what we got from classes. In software development adding unnecessary stuff is second worst to not having enough necessary stuff. In order to figure out what people’s intuition tells them about functionality that is in a class let’s examine what what classes do for us:
- Classes allow us to have data or context with functions, so that consequent calls to functions that belong to the same class maintain that context. This is done through “this” or “self” reference (or pointer).
- Classes give us an ability to pass a set of functions together that all comply to a signature but could be implemented in a variety of ways and possibly even different way depending on which object is being passed around. This is done through virtual function table (vtable).
When choosing to use a class as opposed to a function with parameters the programmer is signaling to the readers: I have some context or some functionality that needs to travel together. If you use classes only when you need class functions it’s a wonderful way to signal to the reader that the context is important.
Unfortunately I see code writers who have grown up on OOP overuse classes and interfaces so the code readers then have to look inside of the class to see whether or not there is data or implementation context that is relevant here.
Simple functions don’t carry context around, by using them your tipping off the readers intuition that there is no context here outside of the parameters being passed in and return values (caveat are global variables and data storage, but that’s a separate topic).
The resulting rule of thumb is to keep it simple unless it needs to be more complex and in languages that support both functional and object oriented programming - use functions unless context or interface/implementation decoupling is necessary. In places where you kept things simple the readers will be able to use their intuition and decrease their cognitive load.
References:
https://typicalprogrammer.com/what-does-code-readability-mean
https://www.butterfly.com.au/blog/website-development/clean-high-quality-code-a-guide-on-how-to-become-a-better-programmer
https://medium.com/machine-words/the-rise-and-fall-of-object-oriented-programming-d67078f970e2
There are books and numerous articles on software design, patterns and naming conventions. I encourage everyone to read those, this blog post is not an attempt to create and exhaustive guide to writing good code. Here I am going to cover a few small hacks that help people understand what your are doing faster. The first topic of discussion is classes.
Java took OOP to an extreme and required you to have a class for every function. This took out an important signal from what we got from classes. In software development adding unnecessary stuff is second worst to not having enough necessary stuff. In order to figure out what people’s intuition tells them about functionality that is in a class let’s examine what what classes do for us:
- Classes allow us to have data or context with functions, so that consequent calls to functions that belong to the same class maintain that context. This is done through “this” or “self” reference (or pointer).
- Classes give us an ability to pass a set of functions together that all comply to a signature but could be implemented in a variety of ways and possibly even different way depending on which object is being passed around. This is done through virtual function table (vtable).
When choosing to use a class as opposed to a function with parameters the programmer is signaling to the readers: I have some context or some functionality that needs to travel together. If you use classes only when you need class functions it’s a wonderful way to signal to the reader that the context is important.
Unfortunately I see code writers who have grown up on OOP overuse classes and interfaces so the code readers then have to look inside of the class to see whether or not there is data or implementation context that is relevant here.
Simple functions don’t carry context around, by using them your tipping off the readers intuition that there is no context here outside of the parameters being passed in and return values (caveat are global variables and data storage, but that’s a separate topic).
The resulting rule of thumb is to keep it simple unless it needs to be more complex and in languages that support both functional and object oriented programming - use functions unless context or interface/implementation decoupling is necessary. In places where you kept things simple the readers will be able to use their intuition and decrease their cognitive load.
References:
https://typicalprogrammer.com/what-does-code-readability-mean
https://www.butterfly.com.au/blog/website-development/clean-high-quality-code-a-guide-on-how-to-become-a-better-programmer
https://medium.com/machine-words/the-rise-and-fall-of-object-oriented-programming-d67078f970e2
Comments