User:Badon/Extension:Semantic MediaWiki/Manual/Semantic naming best practices
Originally from here:
http://old.nabble.com/Semantic-naming-best-practices--to32421403.html
OK, there's a few things we have to name:
- Template call parameters
- Properties (in the template definition)
The template call, with parameters, looks like this:
{{My semantic template call
|Property1=My property 1
|Property2=My property 2
|Property3=My property 3
}}
The template definition for "My semantic template call" would have properties that look like this:
[[Property1::{{{Property1|}}}]]
[[Property2::{{{Property2|}}}]]
[[Property3::{{{Property3|}}}]]
My question is, what should those look like? Let's say that:
- Property1 is a color
- Property1 is a city
- Property1 is a set
So, I THINK I should name the properties like this, respectively:
- Has color
- Is city
- Belongs to set
In the template call, the parameters would be named like this:
{{My semantic template call
|Color=My property 1
|City=My property 2
|Set=My property 3
}}
with the qualifiers ""Has", "Is", and "Belongs to" being semantically unnecessary.
The template definition for "My semantic template call" would have properties named like this:
[[Has color::{{{Color|}}}]]
[[Is city::{{{City|}}}]]
[[Belongs to set::{{{Set|}}}]]
Does that look correct?
I did some reading about parts of speech to figure out what exactly to call this:
My conclusion is that "it" ("Has", "Is", "Belongs to", etc) can be many different parts of speech, but they're always of the form:
Qualifier-object
So, I've decided to just call each part exactly that, either a "qualifier" or an "object". For example, in "Has color", the qualifier is "Has" and the object is "color".
At first the importance of this naming convention was not apparent to me. In a discussion I had with Yaron, he pointed out that there is ambiguity in referring only to an object called "City". Does your property have a city, is it a city, does it belong to a city? And so forth...
I discovered another instance where unambiguous naming can be important. Let's say you have a property called "Color", but you realize that you need to change them all to "Has color" so you can add new properties called "Is color" (red, blue, etc) and "Has particle color" (particle physics "colors").
So, you decide to use the Replace Text extension to change them all from "Color" to "Has color", but your wiki is already full of references to the other types of "color". If you try to replace only the properties named "Color" in your wiki, you will probably also accidentally change every instance of the word "color", even when it's not even a property.
If you had begun your wiki with a best-practice naming convention that was unique to properties, such as always putting them in the form Qualifier-object, then you'll have more luck doing mass changes without accidentally changing something that wasn't supposed to be changed.
Does this make sense? If so, then perhaps the template call should instead look like this, with qualifiers:
{{My semantic template call
|Has color=My property 1
|Is city=My property 2
|Belongs to set=My property 3
}}
And the template definition's properties and parameters should be identical, using same Qualifier-object form:
[[Has color::{{{Has color|}}}]]
[[Is city::{{{Is city|}}}]]
[[Belongs to set::{{{Belongs to set|}}}]]
In short, maybe EVERYTHING involving properties should be in the Qualifier-object form, just to always be semantically clear that it is something involving semantic properties. Thoughts? Does it look like I've got this correct? Should I write it up as best-practice documentation now? Is there anything missing, or something I haven't considered?