Computing for Everyone: Words to avoid in software, aspirational edition

The two hard things in software are cache invalidation and naming things. We haven't talked here yet about caches, yet alone their invalidation, but recent events triggered my desire to address a subtopic about naming.

As your future adjunct professor, I forbid you from using any of the following words in your names:

• generic
• simple
• standard
• reusable
• extensible
• pluginable

These words represent ideals your software should embody, but these words should never be part of your class names, variable names, namespace names, or overall system branding. Here's why.

Human psychic energy is limited.

Well-written code respects the limited psychic energy the maintainers can devote to understanding and making changes to it. Well-written code will minimize the effort required for someone new to a system to take any stanza of code from the system, understand the purpose of the stanza, and convince himself that the stanza correctly implements the intended purpose.

Names are among mankind's most significant allies in understanding software. Computers are happy to distinguish between variables named llllIlll and lllIllll, but humans will go insane dealing with such code in the long-term, have a huge ramp-up time understanding existing code bases written this way in the medium-term, and be much more likely to introduce errors while making changes vital to the mission of a system in the short-term.

Good names in software, then, refer to the problem domain they are addressing, rather than architectural goals. "simpleExtensibleField1" and "simpleExtensibleField2" as variable names are vastly inferior to "subtotal" and "tax".

The problem with the above list is that the extra words make the variables sound different to a computer, but add noise for a human. There's a temptation to brand large refactoring efforts as any of these words, but these refactoring efforts can end halfway through. Then another refactoring effort comes in on the half-refactored code base, sees their favorite word was taken and uses a different word from the list. While refactoring is supposed to make a code base easier to understand without changing its functionality, these sorts of names do the opposite. It would, in fact, be clearer to a human if these efforts had been branded in variable names with colors instead (not that you should do that, either). By way of example, it's much easier to remember if you're working with all GreenWhatchaMadoogies or all YellowWhatchaMadoogies rather than all GenericWhatchaMadoogies or all PluginableWhatchaMadoogies. And really, if the code is actually simple or generic, rather than just insisting via variable names that it is, the code would refer to instances of WhatchaMadoogies rather than either of the preceding. The "generic"/"simple" labels, having failed their mission, are reduced to brands.