Developers spend a lot more time on reading code than writing it. Therefore, if we want to get more effective, we must take a deep look at the reading part. In this Workshop Mark Seemann uses a set of heuristics to address the common obstacles developers face when it comes to understanding code.
Keep in mind that heuristics are a rule of thumb that you always should take with a grain of salt. They may be a great help for certain situations but may miss important details in others.
The Magical Number Seven
The Magic number 7 (plus or minus two) by George Armitage Miller is a paper that provides evidence for the capacity of short-term memory. We can keep only between 5 to 9 items in our short-term memory before our brain reaches its limits. That limit is the scientific backing of many of the heuristics shown in the workshop.
Reduce mental load with checklists
Checklists can be a great help to not forget important steps. If we use them as intended by the pilots who came up with them in the first place and not as a micro-management tool, we can write down all the important things that get easily overlooked in the heat of the moment. Those checklists can be small or large, as long as they help you to remember all the important parts. For a new project, you could go with this checklist:
Especially the advice to turn on errors early in the project forces you to address problems found by the compiler or linters right away. If you fix those problems, you will never reach a level of errors that you no longer can handle.
Keeping complexity down
The main part of making code hard to understand is complexity. That goes through the whole application down to each method. We can start to notice the code smell of too much complexity long before it is a problem. Unfortunately, that is also the point in which one can argue endlessly about the actions to take.
Metrics like the cyclomatic complexity can help us to get an objective measurement on how much is going on in a method. We can calculate it by starting with 1 and count the if-keywords, each case in a switch statement and all the loop statements (for, foreach, do, while). Or we use a tool like the CodeMaintainability 2022 extension for Visual Studio that can show us the cyclomatic complexity of every method right next to the method name.
With the counting defined, we only need to agree on a threshold we do not want to exceed. From there on we can put an end to endless discussions and address the complexity.
Fakes, not mocks
If we make changes to an interface, we need to update all classes that implement the interface and the code that uses it. This is expected to happen and inevitable. If we use dynamic mocks where we use this interface in the setup part, we need to update a lot of tests as well. That part hurts and slows us down when we refactor our application.
With a fake object we can reduce this extra effort massively. Instead of defining the same dynamic mock in every test, we create a fake implementation and use that instead. This reuse of a test double means less places we need to touch when the interface changes and that makes refactoring a lot faster.
Even if we need multiple fake objects in our tests, we still massively reduce the number of places where we need to fix our test setup.
As a side note: We got the same benefits with hiding our dynamic mocks behind the builder pattern. This gives us a bit more flexibility while still reduces the places we need to fix when something changes.
The book
You find all those topics and many more like encapsulation and affordance in the book “Code That Fits in Your Head” by Mark Seemann. You can buy it InformIT or Amazon.
Conclusion
This was a workshop with a lot of practical advice that I can use right away. Mark did a great job of picking easy to use concepts that help to reduce complexity without needing much upfront effort. I can highly recommend this workshop.
1 thought on “NDC Oslo 2022 Workshop: Code That Fits in Your Head”