NepenthesOdyssey: 1 revision imported

2025-02-25T09:35:39Z

1 revision imported

New page

'''Naming things''' is hard.

<blockquote>"There are two hard things in computer science: cache invalidation, naming things, and off-by-one errors." – Leon Bambrick<ref>https://martinfowler.com/bliki/TwoHardThings.html</ref><ref>https://nitter.net/secretGeek/status/7269997868</ref></blockquote>

== General advice ==
;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]], [[wikitech:Help:Labs_labs_labs|Labs labs labs]], [[Extension:Collection|Collection]] vs [[Mobile web projects/Collections Backend|Collections]], [[Page Previews]] vs [[Help:Editing pages#Preview|page previews]])
;Make it easy to pronounce, to type, and to remember
* Avoid [[w:Leet|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., [https://translatewiki.net/wiki/Special:Translations?message=betafeatures-toplink&namespace=8 BetaFeatures] (cf. [[phab:T58537|T58537]]))
* Is the name going to be extra-long in any language? (e.g., [https://translatewiki.net/w/i.php?title=Special%3ATranslations&message=Help&namespace=8 help], [https://translatewiki.net/w/i.php?title=Special%3ATranslations&message=randompage&namespace=8 randompage], <sup>[better examples?]</sup>)
* 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., [[Page Curation|PageTriage/Page Curation/Newpagepatrol/Newpagesfeed]], or [[Echo|Echo/Notifications]], or [[Hovercards|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: [https://php.net/reserved.keywords PHP reserved keywords] and [https://puppet.com/docs/puppet/5.0/lang_reserved.html Puppet reserved words].

== See also ==
* [[Differences between Wikipedia, Wikimedia, MediaWiki, and wiki]]
* [[Manual:Glossary]]
* [[m:Glossary]]
* [[Inclusive language]]

== Further reading ==
; Wikipedia articles
* [[w:en:Naming convention (programming)|Naming convention (programming)]]
* [[w:en:Product naming#International considerations|Product naming#International considerations]]
* [[w:en:Computer network naming scheme|Computer network naming scheme]]
* [[w:en:Yoda conditionals|Yoda conditionals]]
;Humour
* [https://xkcd.com/910/ xkcd.com/910 - Permanence]
* [[rfc:2100|RFC 2100: The Naming of Hosts]]
* [https://www.slideshare.net/unruthless/even-naming-this-talk-is-hard Even Naming This Talk Was Hard] slides ([https://www.youtube.com/watch?v=RFfpkrbkvxc&list=PLZAeFn6dfHpkBld-70TsOoYToM3CaTxRC&index=9 video presentation] 25min) by Ruthie BenDor, at Write the Docs Portland 2017
;Other
* [https://namingschemes.com/ namingschemes.com]
* [[rfc:1178|RFC 1178: Choosing a Name for Your Computer]]
* [https://a-nickels-worth.blogspot.ca/2016/04/a-guide-to-naming-variables.html "A Guide to Naming Variables"]
* [https://web.archive.org/web/20161227073219/https://cc2e.com/Page.aspx?hid=225 Code Complete 2nd Edition Chapter 11: Power of Variables Names - checklist] (archived from the [http://cc2e.com/Page.aspx?hid=225 original])
* [https://www.kalzumeus.com/2010/06/17/falsehoods-programmers-believe-about-names/ Falsehoods Programmers Believe About <nowiki>[human]</nowiki> Names] (2010)
** [https://shinesolutions.com/2018/01/08/falsehoods-programmers-believe-about-names-with-examples/ Falsehoods Programmers Believe About <nowiki>[human]</nowiki> Names – With Examples] (2018)
* [https://dustri.org/b/horrible-edge-cases-to-consider-when-dealing-with-music.html Horrible edge cases to consider when dealing with music]
* [https://ntietz.com/blog/name-your-projects-cutesy-things/ Names should be cute, not descriptive]

== References ==
<references />

[[Category:Documentation]]

Naming things - Revision history

NepenthesOdyssey: 1 revision imported