Naming things
Aus wissen.becker-heiko.de
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
- 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.
- Abbreviations
- 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
- wikitech:Labs labs labs
- Beta beta beta
- Differences between Wikipedia, Wikimedia, MediaWiki, and wiki (aka. "wiki[m/p]edia", etc)
- Yoda conditionals in Manual:Coding conventions/JavaScript#Equality
Further reading
- Wikipedia articles
- Humour
- xkcd.com/910 - Permanence
- Domain Name Humor
- Even Naming This Talk Was Hard slides (video 25min) by Ruthie BenDor, at Write the Docs Portland 2017
- Other
- namingschemes.com
- RFC 1178
- "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
