WriteTheDocs 2017 – Even naming this talk is hard

Speaker: Ruthie BenDor

Software development is predominantly working with other people's code. This means we have to get to know their code, integrate it into our mental model, and determine if we even want to use it. And the most important factor in this is … names.

Why is this so hard?

  • Well, all the good names are already taken. Imagine starting a software project. Since about a million persons did this beforehand, all comprehensible names are already taken. See also wordlab, domaonr, wordroid. Let's just not solve this problem today.
  • Naming of things within software can be hard, too. Because names get overridden, meaning is fluid. (What even is a container.)
  • Naming is reduction, and we are really bad at choosing what to exclude.
  • Names evoke, and we are bad at anticipating what. (Master/Slave, Blacklist/Whitelist, "Kill orphans with cookies"). "The problem is that being technically correct is not always the most emotionally intelligent choice".
  • Naming is guesswork, we often guess wrong, and then we don't go back and correct ourselves.
  • Because naming matters even when we think it doesn't.

"We discover what our software does as we write it."

Why do bad names persist?

  • We don't realize the name is bad, either due to lacking empathy or lacking knowlege, e.g. in terms of localization.
  • We can't or won't justify fixing it, due to overattachment, or overestimation the effort, or underestimating the value.

What makes a name good or bad?

  • Appropriate length
  • Adhere to style guide if managable
  • Avoid ambiguity unless that is the point
  • Easy to pronounce within reason
  • Be memorable, but for the right reasons

Bad names confuse, frustrate, misguide, obscure, offend. Good names contextualize, explain, illuminate, empower.

How can we name software better?

You can use linters to check names, and cross-reference with existing code base, but in the end … it is a judgement call.

So: if we encounter a badly named method or project, remember: It's been named by a poor flawed human being.