Clean Code Tip 4: Don't make reader to think

When code is difficult to understand, the reader must pause to process its meaning, which slows the reading pace. Each instance requiring additional thought interrupts the flow, as the reader can only proceed after comprehending the previous segment. Therefore, code should be written to minimize unnecessary cognitive effort and facilitate faster reading. Several factors may prompt a reader to pause and reflect:

• Obscure identifiers: When names like result are used, readers have to pause and figure out what the variable, class, or function actually represents. For example, someone might wonder, 'Result of what?' Similarly, names like duration or height can be unclear if they don’t specify the units, making readers stop and guess what those units are.

• Too short identifiers (such as 1-2 characters): Extremely brief identifiers require readers to pause and interpret their meaning. For example, variables named i or j lack descriptive value and do not convey their intended purpose.

• Overly long identifiers (approximately 20 characters or more): Excessively lengthy identifiers can overwhelm working memory, making comprehension difficult. Readers may need to reread such names multiple times. Eliminating unnecessary words and using abbreviations enhances readability. For example, ApplicationContextConfigurationManagerImpl can be simplified to AppConfigManager.

---

If you are interested in reading more about clean code, grab yourself a copy of my 140 Tips For Clean Code booklet.