Vlad's Roam Garden

when we read code we execute the search algorithm in our mind

Evergreen clean code readability Cognitive Complexity overview note search algorithm make-public

When we read code - we start from some entry point and from it we proceed to parse the code in our heads in an attempt to discover its meaning. Ensuring that this search can be performed as fast as possible is one of the core responsibilities of any Software Engineer.

The following things help with this:

Respecting level of abstraction

When you do this properly - you transform linear search into something akin to B-tree search.

Within one level of the tree the statements are on the same level of abstraction making it so you don't have to mentally switch between different contexts

And at the same time each node is a pointer to the code on the lower level of abstraction. Where you can navigate to if required.

functions should be small

From the computational perspective this harmonizes with the idea of executing the tree search on the code you're reading. As it moves code in a direction that would minimize the amount of linear search we are required to perform at any given node.

the meaning of the code abstraction should be obvious from the call site

If it's not the case you are forced to explore the subtree to extract its meaning decreasing the speed of the search.

minimize visual noise in your code

Any redundant syntax/symbols add to the amount of things you need to parse

though with time you learn to ignore some of these redundant details if they are inevitable

At the same time - be careful not to remove essential context.

Referenced in

Use Long Names for Long Scopes

when we read code we execute the search algorithm in our mind

readability can be understood in computational terms

when we read code we execute the search algorithm in our mind