change amplification

the first symptom of complexity is that a seemingly simple change requires code modifications in many different places. so one of the goals of good design is to reduce the amount of code that is affected by each design decision, so design changes don’t require very many code modifications.

Link to original

cognitive load

Cognitive load means how much a developer needs to know in order to complete a task. A higher cognitive load means that developers have to spend more time learning the required information and there is a greater risk of bugs because they have missed something important. cognitive load arises in many forms such as APIs with many methods, global variables inconsistencies, and dependencies between modules.

System designers sometimes assume a wrong assumption that complexity can be measured by lines of code. they assume that if one implementation is shorter than another, then it must be simpler; if it only takes a few lines of code to make a change, then the change must be easy however this view ignores the costs associated with the cognitive load I have seen frameworks that allowed applications to be written with only a few lines of code but it was extremely difficult to figure out what those lines where.

Sometimes an approach that requires more lines of code is actually simpler because it reduces the cognitive load

Link to original

unknown unknowns

the third symptom of complexity is that it is not obvious which pieces of code should be modified to complete a task, or what information a developer must have to carry out the task successfully. Of the three manifestations of complexity, unknown unknowns are the worst. an unknown unknowns means that there is something you need to know but there’s no way for you to find out what it is, or even whether there is an issue or not. you won’t find out about it until bugs appear after you make a change.

change amplification is annoying but as long it is clear which code needs to be modified. the system will work once the change has been completed. similarly, a high cognitive load will increase the cost of a change but if it is clear which information to read, the change is still likely to be correct.

with unknown unknowns it’s unclear what to do or whether a proposed system is impossible for the system for any size. even this may not be sufficient, because a change may depend on a subtle design decision that was never documented.

One of the most important goals of a good design is for a system to be obvious. this is the opposite of high cognitive load and unknown unknowns. in an obvious system, a developer can quickly understand how existing code works and what is required to about what to do.

Link to original