naming-principles - Revision history

Aaronpk: Replace with {{DISPLAYTITLE:}}

2020-07-18T16:30:50Z

Replace <entry-title> with {{DISPLAYTITLE:}}

← Older revision		Revision as of 16:30, 18 July 2020
Line 1:		Line 1:
	~~<entry-title>~~Naming Principles~~</entry-title>~~		{{DISPLAYTITLE:Naming Principles}}
	One of the key [[microformats]] [[principles]] is re-use, and in particular, re-use of names of objects, properties, and values from existing formats and standards when possible.		One of the key [[microformats]] [[principles]] is re-use, and in particular, re-use of names of objects, properties, and values from existing formats and standards when possible.

Tantek: Referrers - Gov.UK

2016-08-26T02:48:31Z

Referrers - Gov.UK

← Older revision		Revision as of 02:48, 26 August 2016
Line 26:		Line 26:
	It's also bad for language and communication among humans (e.g. see [[minimal-vocabulary#the_Anglo_centric_renaming_anti_pattern\|the Anglo-centric renaming anti-pattern]]). Even though humans can deal with some ambiguity and overloading of terms (using context to disambiguate), it's easier for humans as well when there is less ambiguity and less overloading.		It's also bad for language and communication among humans (e.g. see [[minimal-vocabulary#the_Anglo_centric_renaming_anti_pattern\|the Anglo-centric renaming anti-pattern]]). Even though humans can deal with some ambiguity and overloading of terms (using context to disambiguate), it's easier for humans as well when there is less ambiguity and less overloading.

	=== documenting principles helps ===		=== documenting principles helps ===
	We're not going to be able to fully eliminate such "Tower of Babel" tendencies, but at least we can minimize them, especially when they are bad for standards and interoperability.		We're not going to be able to fully eliminate such "Tower of Babel" tendencies, but at least we can minimize them, especially when they are bad for standards and interoperability.

Line 151:		Line 151:
	{{main\|minimal-vocabulary#the_Anglo_centric_renaming_anti_pattern}}		{{main\|minimal-vocabulary#the_Anglo_centric_renaming_anti_pattern}}
	Avoid renaming vocabulary when reusing from other specifications. Even if you think you are picking a more understandable ''English'' term, you are actually making it more confusing to non-native-English developers, and you are going to waste even diligent native-English developers' time wondering if the two terms (your new "better" term, and the original term) mean exactly the same thing or not. Why even allow for the possibility of confusion? Avoid renaming when reusing.		Avoid renaming vocabulary when reusing from other specifications. Even if you think you are picking a more understandable ''English'' term, you are actually making it more confusing to non-native-English developers, and you are going to waste even diligent native-English developers' time wondering if the two terms (your new "better" term, and the original term) mean exactly the same thing or not. Why even allow for the possibility of confusion? Avoid renaming when reusing.

			== Referrers ==
			* [https://www.gov.uk/service-manual/making-software/apis.html#names-reinforce-conventions GOV.UK Government Service Design Manual: Names reinforce conventions]

	== See Also ==		== See Also ==

TomMorris: removing dead tr.im shortlink

2014-07-23T17:11:18Z

removing dead tr.im shortlink

← Older revision		Revision as of 17:11, 23 July 2014
Line 4:		Line 4:
	;<span id="Author">Author</span>		;<span id="Author">Author</span>
	:[[User:Tantek\|Tantek Çelik]]		:[[User:Tantek\|Tantek Çelik]]
	~~;short URL~~
	~~:http://tr.im/naming~~

	== Introduction ==		== Introduction ==

Tantek: /* Namespaces */ even limited entry-prefixing has been dropped

2013-04-05T23:53:00Z

Namespaces: even limited entry-prefixing has been dropped

← Older revision		Revision as of 23:53, 5 April 2013
Line 148:		Line 148:

	=== Namespaces ===		=== Namespaces ===
	Avoid namespaces or anything resembling namespaces like prefixes (i.e. class names of ''microformat''-''key'']); read [[namespaces-considered-harmful]]. The problem briefly stated is that namespacing or prefixing encourages silo formats (instead of modular formats, one of the [[principles]]) that neither reuse nor are themselves reusable, certainly not in any easy/elegant way. [[hatom\|hAtom]] uses a limited amount of prefixing to [[hatom-faq#Why_does_hAtom_use_class_name_namespaces\|exactly reuse a particular semantic]] from the Atom spec, but even there, uses a generic prefix "entry-" for terms that could then be reused, rather than a specific prefix like "hatom-" which would look awkward in any instance of reuse outside of hAtom.		Avoid namespaces or anything resembling namespaces like prefixes (i.e. class names of ''microformat''-''key'']); read [[namespaces-considered-harmful]]. The problem briefly stated is that namespacing or prefixing encourages silo formats (instead of modular formats, one of the [[principles]]) that neither reuse nor are themselves reusable, certainly not in any easy/elegant way. [[hatom\|hAtom]] uses a limited amount of prefixing to [[hatom-faq#Why_does_hAtom_use_class_name_namespaces\|exactly reuse a particular semantic]] from the Atom spec, but even there, uses a generic prefix "entry-" for terms that could then be reused, rather than a specific prefix like "hatom-" which would look awkward in any instance of reuse outside of hAtom. Note: even this limited use of prefixing with "entry-" has been dropped in [[microformats2]] [[h-entry]], for greater re-use of existing more generic terms.

	=== Anglo centric renaming when reusing ===		=== Anglo centric renaming when reusing ===

Tantek: /* Under Consideration */

2012-07-24T18:57:57Z

Under Consideration

← Older revision		Revision as of 18:57, 24 July 2012
Line 61:		Line 61:
	** 'country' may be ambiguous (name? code?) and thus it is better to keep a specific term 'country-name' to avoid that confusion.		** 'country' may be ambiguous (name? code?) and thus it is better to keep a specific term 'country-name' to avoid that confusion.
	** other specs		** other specs
			*** vCard in RDF re-used 'country-name' from hCard
	*** OGP re-used 'country-name' from hCard		*** OGP re-used 'country-name' from hCard
	*** vCard in RDF re-used 'country-name' from hCard
	</div>		</div>

Tantek: /* Under Consideration */ to-do - turn into an FAQ for now

2012-07-24T18:47:41Z

Under Consideration: to-do - turn into an FAQ for now

← Older revision		Revision as of 18:47, 24 July 2012
Line 58:		Line 58:
	** 'country' already implies ISO country code in some contexts. In particular, in forms (URL to example(s)?) in which the user had to select "Country" and it was just the ISO Country Code that was stored and displayed to the user. (mkowens on IRC)		** 'country' already implies ISO country code in some contexts. In particular, in forms (URL to example(s)?) in which the user had to select "Country" and it was just the ISO Country Code that was stored and displayed to the user. (mkowens on IRC)
	*** '''I believe this is sufficient to keep 'country-name' by demonstrating that the '-name' suffix is not redundant and does add semantic value.''' Thus we would need another real world property name example to test this potential principle before adopting it. - [[User:Tantek\|Tantek]] 18:44, 24 July 2012 (UTC)		*** '''I believe this is sufficient to keep 'country-name' by demonstrating that the '-name' suffix is not redundant and does add semantic value.''' Thus we would need another real world property name example to test this potential principle before adopting it. - [[User:Tantek\|Tantek]] 18:44, 24 July 2012 (UTC)
			**** [[to-do]]: create an [[hcard-faq\|hCard FAQ]] entry for "Why 'country-name' instead of just 'country' in hCard?" with the above reasoning reworded as an answer.
	** 'country' may be ambiguous (name? code?) and thus it is better to keep a specific term 'country-name' to avoid that confusion.		** 'country' may be ambiguous (name? code?) and thus it is better to keep a specific term 'country-name' to avoid that confusion.
	** other specs		** other specs

Tantek: /* Under Consideration */ split potential principle vs. discussion

2012-07-24T18:46:31Z

Under Consideration: split potential principle vs. discussion

@@ Line 44: / Line 44: @@
 ==== Under Consideration ====
 When reusing names from another vocabulary/schema/RFC:
-* '''drop redundant or no-value suffixes'''. Similar to "Plural components are made singular" note above, the point of this principle is to drop suffixes that don't add anything to the term, and thus use a [[simpler]] term when possible. The specific example in mind is 'country-name' which comes from prose description in vCard. The suffix '-name' is redundant or rather is an implied default meaning of the term 'country' (as opposed to say, 'country-code', e.g. Olympics). Just as we changed vCard 'categories' to 'category', it makes sense to change "country name" to just 'country'.
 ** other specs
-*** PoCo uses just 'country'
+*** OGP re-used 'country-name' from hCard
-*** W3C WD-contacts-api uses 'country'
+*** vCard in RDF re-used 'country-name' from hCard
-*** see [[contact-formats]] for related research.
+</div>
 === Unique Root Class Names ===

Tantek: /* Under Consideration */

2012-07-24T18:44:36Z

Under Consideration

← Older revision		Revision as of 18:44, 24 July 2012
Line 52:		Line 52:
	*** the '-name' suffix does provide semantic clarity that the country name as it would be displayed is provided rather than the country code, or shape/polygon or some other aspect of the country. (though perhaps in practice this is not a problem, as 'org' has been sufficient and nearly no one uses 'organization-name' vs. 'organization-unit', and we can always add suffixes later for more details if necessary).		*** the '-name' suffix does provide semantic clarity that the country name as it would be displayed is provided rather than the country code, or shape/polygon or some other aspect of the country. (though perhaps in practice this is not a problem, as 'org' has been sufficient and nearly no one uses 'organization-name' vs. 'organization-unit', and we can always add suffixes later for more details if necessary).
	*** 'country' already implies ISO country code in some contexts. In particular, in forms (URL to example(s)?) in which the user had to select "Country" and it was just the ISO Country Code that was stored and displayed to the user. (mkowens on IRC)		*** 'country' already implies ISO country code in some contexts. In particular, in forms (URL to example(s)?) in which the user had to select "Country" and it was just the ISO Country Code that was stored and displayed to the user. (mkowens on IRC)
			**** I believe this is sufficient to keep 'country-name' by demonstrating that the '-name' suffix is not redundant and does add semantic value. Thus we would need another real world property name example to test this potential principle before adopting it. - [[User:Tantek\|Tantek]] 18:44, 24 July 2012 (UTC)
	*** 'country' may be ambiguous (name? code?) and thus it is better to keep a specific term 'country-name' to avoid that confusion.		*** 'country' may be ambiguous (name? code?) and thus it is better to keep a specific term 'country-name' to avoid that confusion.
	*** other specs		*** other specs

Tantek: /* Under Consideration */ country sometimes means country-code in forms on the web

2012-07-24T18:41:17Z

Under Consideration: country sometimes means country-code in forms on the web

← Older revision		Revision as of 18:41, 24 July 2012
Line 51:		Line 51:
	** counter-arguments:		** counter-arguments:
	*** the '-name' suffix does provide semantic clarity that the country name as it would be displayed is provided rather than the country code, or shape/polygon or some other aspect of the country. (though perhaps in practice this is not a problem, as 'org' has been sufficient and nearly no one uses 'organization-name' vs. 'organization-unit', and we can always add suffixes later for more details if necessary).		*** the '-name' suffix does provide semantic clarity that the country name as it would be displayed is provided rather than the country code, or shape/polygon or some other aspect of the country. (though perhaps in practice this is not a problem, as 'org' has been sufficient and nearly no one uses 'organization-name' vs. 'organization-unit', and we can always add suffixes later for more details if necessary).
	*** 'country' already implies ISO country code in some contexts (mkowens on IRC)		*** 'country' already implies ISO country code in some contexts. In particular, in forms (URL to example(s)?) in which the user had to select "Country" and it was just the ISO Country Code that was stored and displayed to the user. (mkowens on IRC)
	*** 'country' may be ambiguous (name? code?) and thus it is better to keep a specific term 'country-name' to avoid that confusion.		*** 'country' may be ambiguous (name? code?) and thus it is better to keep a specific term 'country-name' to avoid that confusion.
	*** other specs		*** other specs

Tantek: /* Under Consideration */ 'country' already implies ISO country code per mkowens

2012-07-24T18:39:01Z

Under Consideration: 'country' already implies ISO country code per mkowens

← Older revision		Revision as of 18:39, 24 July 2012
Line 51:		Line 51:
	** counter-arguments:		** counter-arguments:
	*** the '-name' suffix does provide semantic clarity that the country name as it would be displayed is provided rather than the country code, or shape/polygon or some other aspect of the country. (though perhaps in practice this is not a problem, as 'org' has been sufficient and nearly no one uses 'organization-name' vs. 'organization-unit', and we can always add suffixes later for more details if necessary).		*** the '-name' suffix does provide semantic clarity that the country name as it would be displayed is provided rather than the country code, or shape/polygon or some other aspect of the country. (though perhaps in practice this is not a problem, as 'org' has been sufficient and nearly no one uses 'organization-name' vs. 'organization-unit', and we can always add suffixes later for more details if necessary).
	*** OGP re-used 'country-name' from hCard		*** 'country' already implies ISO country code in some contexts (mkowens on IRC)
	*** vCard in RDF re-used 'country-name' from hCard		*** 'country' may be ambiguous (name? code?) and thus it is better to keep a specific term 'country-name' to avoid that confusion.
			*** other specs
			**** OGP re-used 'country-name' from hCard
			**** vCard in RDF re-used 'country-name' from hCard

	=== Unique Root Class Names ===		=== Unique Root Class Names ===