Naming things


Naming things is hard.

"There are two hard things in computer science: cache invalidation, naming things, and off-by-one errors." – Leon Bambrick[1]

General advice[edit]

Avoid ambiguity
Search for similar keywords in existing features, extensions, products, and projects, to avoid confusion and a profusion of hatnotes and seealsos. (e.g., Collection vs Collections, Labs vs labs vs labs, Page Previews vs page previews)
Make it easy to pronounce, to type, and to remember
Avoid l33t5p34k, avoid difficult capitalizations (e.g., SyntaxHighlight GeSHi), and don't use dashes if CamelCase is the local convention.
Consider the translations
If it is a user-facing feature, this is extra important. Is the word almost-untranslatable or extra-long, in any discoverable language? (e.g., help, randompage, BetaFeatures (T58537), [better examples needed...] ) Metaphors and idioms may have different meanings in other languages or cultures.
Check it isn't a reserved keyword in the usual programming languages
This can lead to additional complexity in the code (e.g., Echo). For example: Puppet reserved words.
For long names, specify the short form. People tend to shorten anything they can, especially if they write it regularly, as help-desk people and developers tend to do. Contractions/Initialisms/Acronyms will be invented, if you don't plan for it. (e.g., visual editor is "VE" to many people, see also m:Glossary and Manual:Glossary)
Stick with a single name
Try to pick just one name, for both the code & the user-facing product name. Otherwise you'll have to regularly explain the past/alternative names, and deal with persistent confusion. (e.g., Page-triage/Page-curation/Newpagepatrol/Newpagesfeed, or Echo/Notifications, or Popups/Hovercards/PagePreviews). Renaming things is even harder: the first name used in public is likely to stick, even if you think it's terrible.
Use inclusive language

See also[edit]

Further reading[edit]

Wikipedia articles