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][2]
General advice
[edit]- Avoid ambiguity
- Search for similar keywords in existing features, extensions, products, and projects, to avoid confusion and a profusion of hatnotes, redirects, and See Alsos. (e.g., Beta beta beta, Labs labs labs, Collection vs Collections, Page Previews vs page previews)
- Make it easy to pronounce, to type, and to remember
- Avoid l33t5p34k
- Avoid difficult capitalizations (e.g., SyntaxHighlight GeSHi)
- Don't use dashed-words if CamelCase is the local convention
- Consider the translations
- If it is a user-facing feature, this is extra important.
- Is the name almost-untranslatable in many languages? (e.g., BetaFeatures (cf. T58537))
- Is the name going to be extra-long in any language? (e.g., help, randompage, [better examples?])
- Metaphors, idioms, and pop-culture references may have no meaning or different meanings in other languages or cultures.
- Abbreviations
- For unavoidably 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)
- 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., PageTriage/Page Curation/Newpagepatrol/Newpagesfeed, or Echo/Notifications, or Popups/Hovercards/Previews/Page Previews).
- Renaming things is even harder: the first name used in public is likely to stick, even if you think it's terrible.
- 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: PHP reserved keywords and Puppet reserved words.
See also
[edit]- Differences between Wikipedia, Wikimedia, MediaWiki, and wiki
- Manual:Glossary
- m:Glossary
- Inclusive language
Further reading
[edit]- Wikipedia articles
- Naming convention (programming)
- Product naming#International considerations
- Computer network naming scheme
- Yoda conditionals
- Humour
- xkcd.com/910 - Permanence
- RFC 2100: The Naming of Hosts
- Even Naming This Talk Was Hard slides (video presentation 25min) by Ruthie BenDor, at Write the Docs Portland 2017
- Other
- namingschemes.com
- RFC 1178: Choosing a Name for Your Computer
- "A Guide to Naming Variables"
- Code Complete 2nd Edition Chapter 11: Power of Variables Names - checklist (archived from the original)
- Falsehoods Programmers Believe About [human] Names (2010)
- Horrible edge cases to consider when dealing with music
- Names should be cute, not descriptive