Naming things

From MediaWiki.org
Jump to: navigation, search

Naming things is hard.

"There are two hard things in computer science: cache invalidation, naming things, and off-by-one errors." - Martin Fowler[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/seealsos. (e.g. Collection vs Collections, Labs vs labs vs labs)
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, [better examples needed...] )
Check it isn't a reserved keyword in the usual programming languages 
This can lead to additional complexity in the code. (e.g. Echo)
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. (e.g. Page-triage/Page-curation/Newpagepatrol/Newpagesfeed, Echo/Notifications, Popups/Hovercards/PagePreviews)

See also[edit]

Further reading[edit]

References[edit]