Home > coding, rants > Speed of understanding

Speed of understanding

Is your code easy to understand, can someone new to the codebase grasp quickly most of the intent of the code? What is the speed of understanding of your code.While this is basically the old idea that code should be readable by humans – that includes business people and managers 😉 -, what strategies and tactics can you put in place to gain speed of understanding as an intrinsic quality in your codebase?The thing is that very rarely someone who actually wrote the code is the one that will also maintain for the entire lifetime of the software (and, well, even in that case, knowledge about a codebase is one of the most ephemeral things in life, especially in the case of significant – read, large – codebases).

When a codebase is not so well organized, it very quickly becomes so confusing that even the original team members find themselves scrambling and frantically searching through the codebase in order to find that snippet they wanted to reuse, that pesky function the name of which they can’t recall ( for some reason, some pieces of code or some function names are much harder to commit to memory and find quickly. Treat that as a warning that some action is needed there!).I assume that we are naturally working in a OOP environment, which probably lends itself best, although of course functional languages and strange beasts like javascript can do the trick as well.Two of the strategies (or tactics maybe) that help the most are:


  • Use of DDD, a well codified plain-object domain that models / reflects your business, which is how DDD goes about creating a shared vocabulary between business and engineering. That will lead you to having a DSL for the business domain.
  • Write the client code first – the client code that you would like to have to write. This scenario is greatly enabled by having some DSL first, and, of course, hindered by not having that DSL in place. This is similar to using TDD in what some call “outside in” TDD.


These are for me strategies, more that mere tactics. Both are supported of course by TDD, as you can actually use TDD as a “discovery” too for that client code you want to be writing. However, I am willing to bet that if you have non-trivial business knowledge about your domain already, you can skip that process of discovery and write the code you want to see (as in “be the change you want to see”, you know ), without that meaning “do not back up your code with tests.”  That being said,  it is easier said than done of course.


governance frameworks


Now, there are tactics as well. Nothing trailblazing here:


  • Excellent naming conventions and the discipline to uphold them. It’s already a distant past when one had to save precious bytes by being skimpy on names. Not anymore. Probably only in the case of lambdas, pattern matching, etc. should you be getting away with names like, x, _, temp, and so on.
  • Good commenting habits (there is a lot on this in that great book – Code Complete)
  • Refactoring to small single-purpose functions.
  • Do not overdo the “look ma how smart I am”. Sometimes, they say write code that is not “so smart” (clever one-liners just because I can, nested ternary operators, complicated lambdas), and while that is true to the extent that you don’t want to write production code like this or this, that does not mean you do not take advantage of (relatively) “advanced” features in your language, for fear that other developers coming in later are not familiar with those. They might never learn those!
  • Consistent style in all things: naming, spaces, indenting.
  • Share the code. Have other developers from other teams have a look. Even ask a lay person, your boss for example, to guess what a piece of code does.


You need to use the strategies underpinned by the tactics to achieve that speed of understanding.Would there be a way to actually measure that quality of speed of understanding? I am not that smart to figure that out. Probably not in an absolute way, as there are different styles and preferences for programming – some like fluent api style, others call it the train wreck, for example.For the time being maybe, it’s enough that you always keep that purpose in the back of your mind when coding, until it becomes a habit.
Let me have this as one purpose of mindfulness in coding from now on. Let’s be more aware of this when designing and coding.

Categories: coding, rants Tags: , ,
  1. No comments yet.
  1. March 21st, 2016 at 18:51 | #1