Difference between revisions of "naming-principles"

From Microformats Wiki
naming-principles
Jump to navigation Jump to search
m (typo)
m (reverted to last English version of page)
Line 1: Line 1:
<h1>Principes de Nomenclature</h1>
+
<h1>Naming Principles</h1>
  
L'un des principes-clés des [[microformats-fr|microformats]] est de réutiliser et en particulier, réutiliser les noms d'objets, de propriétés et de valeurs à partir des formats existants et des standards à chaque fois que cela est 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
  
J'ai créé explicitement ce principe en réponse aux anti-modèles que j'ai vus dans beaucoup (la plupart ?) des efforts de standards existants tels que :  
+
I explicitly created this principle in response to the anti-patterns that I saw in many (most?) existing standards efforts such as:
  
* Inventer des noms en l'air
+
* Making up names from thin air
* Ignorer tous les travaux précédents
+
* Ignoring all earlier work
* Hostilité véritable envers les noms/termes provenant d'autres standards
+
* Actual hostility towards using names/terms from other standards
* Utiliser les noms des autres pour signifier des choses différentes
+
* Using others' names to mean different things
* Utiliser de nouveaux noms pour signifier la même chose
+
* Using new names to mean the same thing
* Débattre sans fin et "forger-des-noms" afin de parvenir à un nom légèrement plus parfait.
+
* Endlessly debating and "name-smithing" in order to come up with a slightly more perfect name
  
Peut-être est-ce dans la nature humaine de créer de nouveaux noms, ou de nommer de nouvelles choses. Il y a certainement une quantité d'égo impliquée dans la création d'une nouvelle chose que vous pouvez ensuite proclamer avoir inventé ou nommé. Quelques-unes de ces tendances sont aussi une forme de syndrôme "Not Invented Here" (NIH) qui malheureusement est tout à fait commun parmi les ingénnieurs logiciels.
+
Perhaps it is human nature to want to create new names, or name new things. Certainly there is some amount of ego involved in the creation of a new thing which you can then claim to have invented or named. Some of these tendencies are also a form of "Not Invented Here" (NIH) syndrome which unfortunately is quite common among software engineers.
  
Malheureusement, un tel désir pour la nouveauté est mauvais pour les standards, et certainement mauvais pour l'interopérabilité, qui dépend d'être capable de compter sur le même nom voulant dire la même chose. C'est aussi mauvais pour le langage et la communication entre humains. Même si les humains peuvent s'arranger avec quelque ambiguïté et la surcharge de termes (en utilisant le contexte pour la désambiguation), c'est plus facile pour les humains quand il y a moins d'ambiguïté et moins de surcharge).
+
Unfortunately such desire for novelty is bad for standards, and certainly bad for interoperability, which depends on being able to depend on the same name meaning the same thing. It's also bad for language and communication among humans. 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.
  
Nous n'allons pouvoir pleinement éliminer de telles tendances "Tour de Babel", mais au moins nous pouvons les minimiser, tout spécialement quand elles sont mauvaises pour les standards et l'interopérabilité.
+
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.
  
Avec l'expérience de développer de nouveaux microformats tels que [[xfolk-fr|xFolk]], [[hreview-fr|hReview]] et [[hatom-fr|hAtom]], il est devenu tout à fait clair que nous avons besoin de documenter explicitement quelques-uns des principes spécifiques de design qui en sont venus à nommer les objets et propriétés de quelques-uns de premiers microformats établis comme [[hcard-fr|hCard]] et [[hcalendar-fr|hCalendar]], et c'est l'intention de ce document.
+
With the experience of developing new microformats such as [[xfolk|xFolk]], [[hreview|hReview]], and [[hatom|hAtom]], it has become quite clear that we need to explicitly document some of the specific design principles that went into naming the objects and properties of some of the early established microformats like [[hcard|hCard]] and [[hcalendar|hCalendar]], and that's the purpose of this document.
  
<h2>Table des Matières</h2>
+
<h2>Table of Contents</h2>
  
 
__TOC__
 
__TOC__
  
== Auteur ==
+
== Author ==
  
 
* [http://tantek.com/ Tantek Çelik]
 
* [http://tantek.com/ Tantek Çelik]
  
(traduction en cours [[Christophe Ducamp]]
+
== Semantic XHTML Design Principles ==
  
 +
First, it is important to note the naming principles which have been defined and explicitly referenced in (most of) the above-mentioned microformats.
  
== Principes de Design XHTML Sémantique ==
+
{{semantic-xhtml-design-principles}}
  
Tout d'abord, il est important de remarquer les principes de nommages qui ont été définis et explicitement référencés dans (la plupart) des microformats mentionnés ci-dessus.
+
=== Some Details ===
  
{{semantic-xhtml-design-principles-fr}}
+
* '''dash-separated-lowercase-words'''. [http://w3.org/ W3C] [http://w3.org/Style/CSS/ CSS] (cascading style sheets) introduced the convention of lowercasing all property/value names (identifiers) and separating words with dash "-" characters for reasons of better human readability as compared to other approaches like CamelCase (or even camelCase).  Microformats property names strictly adopt this approach as well.
  
=== Quelques Détails ===
+
== Unique Root Class Names ==
  
* '''mots-en-minuscules-séparés-par-des-tirets'''. Les [http://w3.org/ W3C] [http://w3.org/Style/CSS/ CSS] (feuilles de styles en cascades) ont introduit la convention de mettre en minuscules tous les noms de propriétés/valeurs (identifiants) et de séparer les mots avec des caractères trait d'union "-" pour des raisons de meilleure lisibilité humaine comparé à d'autres approches comme la casse ChatMot (ou même casse chatMot). Les noms des propriétés des microformats adoptent tout aussi bien strictement cette approche.
+
I've also written a bit about the design principles that went into the *root* class names (which require a bit different treatment than property class names) in the microformats, but this is described in the hcard-parsing page currently:
  
== Noms de Classe Racine Uniques ==
+
http://microformats.org/wiki/hcard-parsing#root_class_name
  
J'ai aussi écrit un peu à propos des principes de design qui sont allés à l'intérieur des noms de classe *racine* (qui requièrents un traitement un peu différent que les noms de classe propriété) dans les microformats, mais ceci est décrit actuellement dans la page hcard-parsing :
+
Need to copy some of that text here and make it not-hCard specific.
  
http://microformats.org/wiki/hcard-parsing-fr#nom_classe_racine
+
== Minimal Vocabulary ==
  
Besoin de copier un peu de ce texte ici et de faire que ce ne soit pas spécifique à hCard.
+
This is one of two additional key principles that I think I need to outline in more detail.  The principle of "minimal vocabulary" is actually directly derived from the principle of [http://microformats.org/wiki/microformats#the_microformats_principles start as simple as possible].
  
== Vocabulaire Minimal ==
+
* minimal vocabulary.  We try to introduce as few new microformat terms as possible.
  
Ceci est l'un des deux autres principes-clés qui je pense a besoin d'être développé plus en détail. Le principe de "vocabulaire minimal" est en fait directement dérivé du principe de [http://microformats.org/wiki/microformats-fr#les_principes_des_microformats démarrer aussi simple que possible].
+
== Reuse Microformats First, Other Standards Second ==
  
* vocabulaire minimal. Nous essaierons de présenter aussi peu de nouveaux termes de microforomats que possible.
+
This is actually outlined quite clearly in the [http://microformats.org/wiki/microformats#the_microformats_principles microformats principles], but deserves both explicit repeating here with <strong>strong emphasis</strong>:
  
== Réutilisation des Microformats en Premier, Autres Standards en Second ==
+
* reuse building blocks from widely adopted standards
 +
** semantic (http://tantek.com/presentations/20040928sdforumws/semantic-xhtml.html), meaningful (X)HTML (http://tantek.com/presentations/2005/03/elementsofxhtml). See SemanticXHTMLDesignPrinciples for more details.
 +
** <strong>existing microformats</strong>
 +
** <strong>well established schemas from interoperable RFCs</strong>
  
Ceci est en fait développé tout à fait clairement dans les  [[microformats-fr#les_principes_des_microformats|principes des microformats]], mais mérite à la fois une répétition explicite ici avec une <strong>emphase appuyée</strong> :
+
The key here is that this principle is not only about reusing whole microformats (e.g. don't invent a new person property for your microformat, just reuse [[hcard|hCard]]), but also about where to get names for properties.
  
* réutiliser des blocs de construction à partir de standards largement adoptés
+
In particular, if you find that your new microformat has a property which means the same thing as an exsiting microformat, you SHOULD (maybe I should make this a MUST) reuse the class name from that existing microformat. This practice also follows the principle of minimal vocabulary, and of re-using the same name to mean the same thing (instead of using two names to mean the same thing).
** sémantique (http://tantek.com/presentations/20040928sdforumws/semantic-xhtml.html), (X)HTML ayant du sens (http://tantek.com/presentations/2005/03/elementsofxhtml). Voir [[SemanticXHTMLDesignPrinciples-fr|Principes de Design XTHML sémantique]] pour plus de détails.
 
** <strong>microformats existants</strong>
 
** <strong>schémas bien établis à partir de RFCs interopérables</strong>
 
  
La clé ici est que ce principe n'est pas seulement de réutiliser l'ensemble des microformats (par ex. n'inventez pas une propriété pour une nouvelle personne pour votre microformat, réutilisez simplement le [[hcard-fr|hCard]]), mais aussi de savoir où obtenire des noms pour les propriétés.
+
=== For Other Standards, Prefer Older to Newer ===
  
En particulier, si vous trouvez que votre nouveau microformat a une propriété qui veut dire la même chose qu'un microformat existant, vous DEVRIEZ (peut-être que je devrais faire de cela un DEVEZ) réutiliser le nom de classe pour ce microformat existant. Cette pratique suit aussi le principe du vocabulaire minimal, et le fait de réutiliser le même nom pour dire la même chose (au lieu d'utiliser deux noms pour signifier la même chose).
+
If there is no microformat name for a property, and we are reusing names based upon research of existing formats, then often there is more than one format with more than one name for the particular concept.
  
=== Pour les Autres Standards, Préférez les Plus Vieux aux Plus Récents ===
+
Often times new standards are developed which (most often) needlessly rename names from older standards.  Thus to repair such naming drift, all other things being equal (e.g. both standards have been widely interoperably implemented), we prefer the older name over the newer name.
  
S'il n'existe pas de noms de microformat pour une propriété, et que nous réutilisons des noms fondés sur la recherche de microformats existants, alors il y a souvent plus d'un format avec plus qu'un nom pour le concept particulier.
+
== Examples of Following the Naming Principles ==
  
Souvent les nouveaux standards sont développés à partir (la plupart du temps) de renommages inutiles noms provenant des standards plus anciens. De ce fait pour réparer une telle dérive de nom, toutes les choses étant égales par ailleurs (par ex. les deux standards ont été largement implémentés de manière interopérable), nous préférons le noms le plus ancien au nom le plus récent.
+
We've followed these naming principles from the start, and made changes to microformats in development as a result. For example, [[xfolk|xFolk]] was changed from v0.4 to v1RC.  xFolk dropped the new class name "extended" in preference for re-using the existing "description" class name. See [http://microformats.org/wiki/xfolk#Changes_since_xFolk_0.4 Changes since xFolk 0.4] for details.
  
== Exemples pour suivre les Conventions de Nommage ==
+
== Naming Patterns Under Consideration as Principles ==
  
Nous avons suivi ces principes de nommage à partir du début, et produit les changements sur les microformats en développement. Par exemple, [[xfolk-fr|xFolk]] a été modifié de la v0.4 vers la v1RC.  xFolk a laissé tomber le nouveau nom de classe "extended" pour lui préférer la réutilisation du nom de classe existant "description". Voir [[xfolk-fr#Changements_depuis_xFolk_0.4|Changements depuis xFolk 0.4]] pour les détails.
+
A few patterns have arisen in the naming of class names for microformats, and while these patterns are not conventions (yet), it may be worth considering them.
  
== Modèles de Nommage en Considération en tant que Principes==
+
=== dt properties ===
  
Quelques modèles ont émergé dans le nommage de noms de classe pour les microformats, et alors que ces modèles ne sont pas des conventions (à cette heure), il peut être valable de les prendre en considération.
+
So far, all datetime class names start with "dt", and all class names that start with "dt" are ISO8601 datetime properties.  E.g.
  
=== propriétés dt ===
+
* dtend - [[hcalendar|hCalendar]]
 +
* dtstart - [[hcalendar|hCalendar]]
 +
* dtreviewed - [[hreview|hReview]]
  
A ce stade, tous les noms de classe datetime commenent avec "dt", et tous les noms de classe qui démarrent avec "dt" sont de propriétés datetime ISO8601 par ex. :
+
Note that "dt" is also [http://microformats.org/wiki/rest/datatypes#Proposal under consideration for type XOXO].
  
* dtend - [[hcalendar-fr|hCalendar]]
+
==== exceptions to dt prefix ====
* dtstart - [[hcalendar-fr|hCalendar]]
 
* dtreviewed - [[hreview-fr|hReview]]
 
  
Notez que "dt" est aussi [http://microformats.org/wiki/rest/datatypes#Proposal en considération pour le type XOXO].
+
However, some proposed/underdevelopment microformats currently have class names for datetime properties without the "dt" prefix:
  
==== exceptions avec le préfixe dt ====
+
Draft:
 +
* rev - [[hcard|hCard]]
 +
* bday - [[hcard|hCard]]
  
Néanmoins, quelques microformats proposés/en-développement ont actuellement des noms de classe pour les propriétés datetime sans le préfixe "dt" :
+
Proposed:
 
+
* updated - [[hatom|hAtom]]
Brouillon :  
+
* published - [[hatom|hAtom]]
* rev - [[hcard-fr|hCard]]
 
* bday - [[hcard-fr|hCard]]
 
 
 
Proposé :
 
* mis à jour - [[hatom-fr|hAtom]]
 
* publié - [[hatom-fr|hAtom]]
 
  
 
=== h word ===
 
=== h word ===
  
A ce stade, toutes les utilisations d'un préfixe unique "h" dans un nom de propriété s'appliquent aux éléments racines (potentiels). Mais pas tous les éléments racines (potentiels) ne démarrent par "h" (ce qui est "ok").
+
So far, all uses of a single "h" prefix in a property name apply to (potential) root elements.   But not all (potential) root elements start with "h" (which is ok).
  
Par ex. :
+
E.g.:
  
* [[hatom-fr]]
+
* [[hatom]]
* hentry - [[hatom-fr|hAtom]]
+
* hentry - [[hatom|hAtom]]
* [[hreview-fr]]
+
* [[hreview]]
* [[hlisting-proposal-fr|hlisting]] (proposed)
+
* [[hlisting-proposal|hlisting]] (proposed)
  
Devrions nous appliquer la règle que seuls les éléments racines (potentiels) pourraient démarrer par un préfixe "h" ?
+
Should we enforce the rule that only (potential) root elements may begin with an "h" prefix?
  
Les éléments racines non-préfixés-h :
+
Non-h-prefixed root elements:
* vcard - [[hcard-fr|hCard]]
+
* vcard - [[hcard|hCard]]
* vcalendar - [[hcalendar-fr|hCalendar]]
+
* vcalendar - [[hcalendar|hCalendar]]
* vevent - [[hcalendar-fr|hCalendar]]
+
* vevent - [[hcalendar|hCalendar]]
* [[xfolk-fr]]
+
* [[xfolk]]
  
== En rapport : ==
+
== Related ==
  
* [[semantic-xhtml-design-principles-fr]]
+
* [[semantic-xhtml-design-principles]]
* [[naming-conventions-fr|conventions de nommage]] pour les pages du site wiki microformats.org
+
* [[naming-conventions]] for microformats.org wiki pages

Revision as of 15:38, 28 June 2006

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. -Tantek

I explicitly created this principle in response to the anti-patterns that I saw in many (most?) existing standards efforts such as:

  • Making up names from thin air
  • Ignoring all earlier work
  • Actual hostility towards using names/terms from other standards
  • Using others' names to mean different things
  • Using new names to mean the same thing
  • Endlessly debating and "name-smithing" in order to come up with a slightly more perfect name

Perhaps it is human nature to want to create new names, or name new things. Certainly there is some amount of ego involved in the creation of a new thing which you can then claim to have invented or named. Some of these tendencies are also a form of "Not Invented Here" (NIH) syndrome which unfortunately is quite common among software engineers.

Unfortunately such desire for novelty is bad for standards, and certainly bad for interoperability, which depends on being able to depend on the same name meaning the same thing. It's also bad for language and communication among humans. 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.

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.

With the experience of developing new microformats such as xFolk, hReview, and hAtom, it has become quite clear that we need to explicitly document some of the specific design principles that went into naming the objects and properties of some of the early established microformats like hCard and hCalendar, and that's the purpose of this document.

Table of Contents

Author

Semantic XHTML Design Principles

First, it is important to note the naming principles which have been defined and explicitly referenced in (most of) the above-mentioned microformats.

Note: the Semantic XHTML Design Principles were written primarily within the context of developing hCard and hCalendar, thus it may be easier to understand these principles in the context of the hCard design methodology (i.e. read that first). Tantek

XHTML is built on XML, and thus XHTML based formats can be used not only for convenient display presentation, but also for general purpose data exchange. In many ways, XHTML based formats exemplify the best of both HTML and XML worlds. However, when building XHTML based formats, it helps to have a guiding set of principles.

  1. Reuse the schema (names, objects, properties, values, types, hierarchies, constraints) as much as possible from pre-existing, established, well-supported standards by reference. Avoid restating constraints expressed in the source standard. Informative mentions are ok.
    1. For types with multiple components, use nested elements with class names equivalent to the names of the components.
    2. Plural components are made singular, and thus multiple nested elements are used to represent multiple text values that are comma-delimited.
  2. Use the most accurately precise semantic XHTML building block for each object etc.
  3. Otherwise use a generic structural element (e.g. <span> or <div>), or the appropriate contextual element (e.g. an <li> inside a <ul> or <ol>).
  4. Use class names based on names from the original schema, unless the semantic XHTML building block precisely represents that part of the original schema. If names in the source schema are case-insensitive, then use an all lowercase equivalent. Components names implicit in prose (rather than explicit in the defined schema) should also use lowercase equivalents for ease of use. Spaces in component names become dash '-' characters.
  5. Finally, if the format of the data according to the original schema is too long and/or not human-friendly, use <abbr> instead of a generic structural element, and place the literal data into the 'title' attribute (where abbr expansions go), and the more brief and human readable equivalent into the element itself. Further informative explanation of this use of <abbr>: Human vs. ISO8601 dates problem solved

Some Details

  • dash-separated-lowercase-words. W3C CSS (cascading style sheets) introduced the convention of lowercasing all property/value names (identifiers) and separating words with dash "-" characters for reasons of better human readability as compared to other approaches like CamelCase (or even camelCase). Microformats property names strictly adopt this approach as well.

Unique Root Class Names

I've also written a bit about the design principles that went into the *root* class names (which require a bit different treatment than property class names) in the microformats, but this is described in the hcard-parsing page currently:

http://microformats.org/wiki/hcard-parsing#root_class_name

Need to copy some of that text here and make it not-hCard specific.

Minimal Vocabulary

This is one of two additional key principles that I think I need to outline in more detail. The principle of "minimal vocabulary" is actually directly derived from the principle of start as simple as possible.

  • minimal vocabulary. We try to introduce as few new microformat terms as possible.

Reuse Microformats First, Other Standards Second

This is actually outlined quite clearly in the microformats principles, but deserves both explicit repeating here with strong emphasis:

The key here is that this principle is not only about reusing whole microformats (e.g. don't invent a new person property for your microformat, just reuse hCard), but also about where to get names for properties.

In particular, if you find that your new microformat has a property which means the same thing as an exsiting microformat, you SHOULD (maybe I should make this a MUST) reuse the class name from that existing microformat. This practice also follows the principle of minimal vocabulary, and of re-using the same name to mean the same thing (instead of using two names to mean the same thing).

For Other Standards, Prefer Older to Newer

If there is no microformat name for a property, and we are reusing names based upon research of existing formats, then often there is more than one format with more than one name for the particular concept.

Often times new standards are developed which (most often) needlessly rename names from older standards. Thus to repair such naming drift, all other things being equal (e.g. both standards have been widely interoperably implemented), we prefer the older name over the newer name.

Examples of Following the Naming Principles

We've followed these naming principles from the start, and made changes to microformats in development as a result. For example, xFolk was changed from v0.4 to v1RC. xFolk dropped the new class name "extended" in preference for re-using the existing "description" class name. See Changes since xFolk 0.4 for details.

Naming Patterns Under Consideration as Principles

A few patterns have arisen in the naming of class names for microformats, and while these patterns are not conventions (yet), it may be worth considering them.

dt properties

So far, all datetime class names start with "dt", and all class names that start with "dt" are ISO8601 datetime properties. E.g.

Note that "dt" is also under consideration for type XOXO.

exceptions to dt prefix

However, some proposed/underdevelopment microformats currently have class names for datetime properties without the "dt" prefix:

Draft:

Proposed:

h word

So far, all uses of a single "h" prefix in a property name apply to (potential) root elements. But not all (potential) root elements start with "h" (which is ok).

E.g.:

Should we enforce the rule that only (potential) root elements may begin with an "h" prefix?

Non-h-prefixed root elements:

Related