“Bad names make you open the box” is in multiple ways a special case of the more general principle that “Good system architecture is low-context” or “Good system architecture has a sparse understanding-graph”.
If we imagine a graph diagram where each node N representing a part of the system (e.g. a function in a codebase) has edges coming in from all other nodes that one must understand in order to understand N, then a good low-context architecture is one with the fewest possible edges per node.
The post talks about how a badly-named function causes there to be an understanding-edge from the code inside that function to that function. More generally, a badly-architected function requires understanding other parts of the system in order to understand what it does. E.g.:
If the function mutates a global state variable, then the reader must understand outside context about that variable’s meaning in order to understand the function
If the function does a combination of work that only makes sense in the context of your program—rather than being a more program-independent reusable part—then its understanding-graph will have extra edges to various other parts of your program. Or in the best case, where your function is well-documented to avoid imposing those understanding-edges on the reader, you’re still adding extra edge weight from the function to the now-longer-winded docstring.
The “sparse understanding-graph” is also applicable to org charts of people working together. You ideally want the sparsest possible cooperation-graph.
Yup, for sure! I actually really wanted this post to be more general and make these points, but I wasn’t able to explain it well or come up with good examples outside of coding. If you or anyone else wants to piggyback off of my post and write a post about the more general point, I’d love to see it!
“Bad names make you open the box” is in multiple ways a special case of the more general principle that “Good system architecture is low-context” or “Good system architecture has a sparse understanding-graph”.
If we imagine a graph diagram where each node N representing a part of the system (e.g. a function in a codebase) has edges coming in from all other nodes that one must understand in order to understand N, then a good low-context architecture is one with the fewest possible edges per node.
The post talks about how a badly-named function causes there to be an understanding-edge from the code inside that function to that function. More generally, a badly-architected function requires understanding other parts of the system in order to understand what it does. E.g.:
If the function mutates a global state variable, then the reader must understand outside context about that variable’s meaning in order to understand the function
If the function does a combination of work that only makes sense in the context of your program—rather than being a more program-independent reusable part—then its understanding-graph will have extra edges to various other parts of your program. Or in the best case, where your function is well-documented to avoid imposing those understanding-edges on the reader, you’re still adding extra edge weight from the function to the now-longer-winded docstring.
The “sparse understanding-graph” is also applicable to org charts of people working together. You ideally want the sparsest possible cooperation-graph.
Yup, for sure! I actually really wanted this post to be more general and make these points, but I wasn’t able to explain it well or come up with good examples outside of coding. If you or anyone else wants to piggyback off of my post and write a post about the more general point, I’d love to see it!