The Greatest Commandment of Software Engineering

 

 Thou Shalt Minimize Cognitive Load!

Computers don't make mistakes, people do.  Computers do exactly as they're told.  Problems happen when they're told to do the incorrect thing or how to do the correct thing incorrectly.

People make mistakes when they're Hungry, Angry, Lonely, or Tired.  As a matter of dignity, we generally leave it up to the individual to manage this for themselves.  However, there are things we can do at an organizational level to help.  One of these is to reduce the complexity of the individual's problem domain and thereby reduce their tendency towards mental fatigue.  We can do this by striving to keep cognitive load to a minimum.

This has been stated in other ways:

• K.I.S.S - Keep it Simple Stupid
• Principle of Parsimony
• Occam's Razor
  
• A good programmer is lazy
• Eschew Obfuscation

Human cognitive load is said to max out at around 7+/-2.  Helping engineers stay within this range not only reduces mental fatigue but also encourages best practices.  Here are just a few ways that best practices may emerge from following this one principle.

Reduce Loss of Information/Knowledge

Context changes are expensive.  They force an engineer to increase their cognitive load.  In the process they can often lose much of what's been built up over hours of work.  

To keep cognitive load low:

• Maintain quality documentation
  
• Create reliable documentation because you're still gonna get interrupted/distracted
• If it doesn't warrant documentation, use a personal scratch pad
• Adopt a Manager/Maker schedule
•  Group meetings in the morning/evening/meeting days
• Adopt a repeatable workflow for turning ideas into actionable objectives, objectives into atomic chunks of work, chunks of work into deliverables.
• Follow Standard Practices & Patterns
  
• Consistently use intuitive, canonical structures ie. design patterns.  Call them out explicitly.
  

Reduce the Impact of Production Events

Keep cognitive load low by minimizing threat vectors.

Methodically eliminate possible sources of risk.  When an issue arises, you're left w/ only likely causes.  Less hypotheses to test means faster reaction time and reduced impact of production events.

Improve Maintainability & Velocity by Minimizing Complexity

• In Code
  
• Tend toward simple and concise implementations
• Borrow from trusted systems: nature, mathematics, music, language, etc
  
• replication - reuse
  
• symmetry - define a category by specifying only half
  
• consistency/variations on a theme - define variations by tweaks to a common knowledge
  
• Tend toward immutability
  
• If an object will only ever have one state, make that obvious by eliminating any way of changing it
  
• If it changes in minimal ways, restrict possible means of changing it
  
• Tend towards statelessness
• Write methods/objects/applications as a black box.  Their consumers shouldn't need to know how they work.
• Use abstraction tools like Containerization or ORMs to eliminate environment/platform specific sources of variety/complexity
• In process
• Use a CICD pipeline w/ code reviews
• Commit code frequently - don't warehouse changes locally
• Deploy frequently - don't warehouse latent bugs/issues