Difference between revisions of "naming-principles"

From Microformats Wiki
naming-principles
Jump to navigation Jump to search
m (Reverted edit of 1143295502, changed back to last version by Tantek)
(structure translated)
Line 1: Line 1:
<h1>Naming Principles</h1>
+
<h1>Principes de Nomenclature</h1>
  
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.
+
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.
  
I explicitly created this principle in response to the anti-patterns that I saw in many (most?) existing standards efforts such as:
+
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 :  
  
* Making up names from thin air
+
* Inventer des noms en l'air
* Ignoring all earlier work
+
* Ignorer tous les travaux précédents
* Actual hostility towards using names/terms from other standards
+
* Hostilité véritable envers les noms/termes provenant d'autres standards
* Using others' names to mean different things
+
* Utiliser les noms des autres pour signifier des choses différentes
* Using new names to mean the same thing
+
* Utiliser de nouveaux noms pour signifier la même chose
* Endlessly debating and "name-smithing" in order to come up with a slightly more perfect name
+
* Débattre sans fin et "forger-des-noms" afin de parvenir à un nom légèrement plus parfait.
  
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.
+
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.
  
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.
+
Malheureusement, un tel désire pour la nouveauté est mauvais pour les standards, et certainement mauvais pour l'interopérabilité, qui dépend d'être capable de compter surle 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).
  
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.
+
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é.
  
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.
+
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.
  
<h2>Table of Contents</h2>
+
<h2>Table des Matières</h2>
  
 
__TOC__
 
__TOC__
  
== Author ==
+
== Auteur ==
  
 
* [http://tantek.com/ Tantek Çelik]
 
* [http://tantek.com/ Tantek Çelik]
  
== Semantic XHTML Design Principles ==
+
(traduction en cours [[Christophe Ducamp]]
  
First, it is important to note the naming principles which have been defined and explicitly referenced in (most of) the above-mentioned microformats.
 
  
{{semantic-xhtml-design-principles}}
+
== Principes de Design XHTML Sémantique ==
  
=== Some Details ===
+
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.
 +
 
 +
{{semantic-xhtml-design-principles-fr}}
 +
 
 +
=== Quelques Détails ===
  
 
* '''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.
 
* '''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.
  
== Unique Root Class Names ==
+
== Noms de Classe Racine Uniques ==
  
 
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:
 
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:
Line 46: Line 49:
 
Need to copy some of that text here and make it not-hCard specific.
 
Need to copy some of that text here and make it not-hCard specific.
  
== Minimal Vocabulary ==
+
== Vocabulaire Minimal ==
  
 
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].
 
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].
Line 52: Line 55:
 
* minimal vocabulary.  We try to introduce as few new microformat terms as possible.
 
* minimal vocabulary.  We try to introduce as few new microformat terms as possible.
  
== Reuse Microformats First, Other Standards Second ==
+
== Réutilisaton des Microformats en Premier, Autres Standards en Second ==
  
 
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>:
 
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>:
Line 65: Line 68:
 
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).
 
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 ===
+
=== Pour les Autres Standards, Préférez les Plus Vieux aux Plus Récents ===
  
 
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.
 
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.
Line 71: Line 74:
 
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.
 
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 ==
+
== Exemples pour suivre les Conventions de Nommage ==
  
 
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.
 
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.
  
== Naming Patterns Under Consideration as Principles ==
+
== Modèles de Nommage en Considération en tant que Principes==
  
 
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.
 
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 ===
+
=== propriétés dt ===
  
 
So far, all datetime class names start with "dt", and all class names that start with "dt" are ISO8601 datetime properties.  E.g.
 
So far, all datetime class names start with "dt", and all class names that start with "dt" are ISO8601 datetime properties.  E.g.
  
* dtend - [[hcalendar|hCalendar]]
+
* dtend - [[hcalendar-fr|hCalendar]]
* dtstart - [[hcalendar|hCalendar]]
+
* dtstart - [[hcalendar-fr|hCalendar]]
* dtreviewed - [[hreview|hReview]]
+
* dtreviewed - [[hreview-fr|hReview]]
  
 
Note that "dt" is also [http://microformats.org/wiki/rest/datatypes#Proposal under consideration for type XOXO].
 
Note that "dt" is also [http://microformats.org/wiki/rest/datatypes#Proposal under consideration for type XOXO].
  
==== exceptions to dt prefix ====
+
==== exceptions avec le préfixe dt ====
  
 
However, some proposed/underdevelopment microformats currently have class names for datetime properties without the "dt" prefix:
 
However, some proposed/underdevelopment microformats currently have class names for datetime properties without the "dt" prefix:
  
 
Draft:
 
Draft:
* rev - [[hcard|hCard]]
+
* rev - [[hcard-fr|hCard]]
* bday - [[hcard|hCard]]
+
* bday - [[hcard-fr|hCard]]
  
 
Proposed:
 
Proposed:
* updated - [[hatom|hAtom]]
+
* updated - [[hatom-fr|hAtom]]
* published - [[hatom|hAtom]]
+
* published - [[hatom-fr|hAtom]]
  
 
=== h word ===
 
=== h word ===
Line 107: Line 110:
 
E.g.:
 
E.g.:
  
* [[hatom]]
+
* [[hatom-fr]]
* hentry - [[hatom|hAtom]]
+
* hentry - [[hatom-fr|hAtom]]
* [[hreview]]
+
* [[hreview-fr]]
* [[hlisting-proposal|hlisting]] (proposed)
+
* [[hlisting-proposal-fr|hlisting]] (proposed)
  
 
Should we enforce the rule that only (potential) root elements may begin with an "h" prefix?
 
Should we enforce the rule that only (potential) root elements may begin with an "h" prefix?
  
 
Non-h-prefixed root elements:
 
Non-h-prefixed root elements:
* vcard - [[hcard|hCard]]
+
* vcard - [[hcard-fr|hCard]]
* vcalendar - [[hcalendar|hCalendar]]
+
* vcalendar - [[hcalendar-fr|hCalendar]]
* vevent - [[hcalendar|hCalendar]]
+
* vevent - [[hcalendar-fr|hCalendar]]
 
* [[xfolk]]
 
* [[xfolk]]
  
== Related ==
+
== En rapport : ==
  
* [[semantic-xhtml-design-principles]]
+
* [[semantic-xhtml-design-principles-fr]]
* [[naming-conventions]] for microformats.org wiki pages
+
* [[naming-conventions-fr]] for microformats.org wiki pages

Revision as of 14:57, 28 June 2006

Principes de Nomenclature

L'un des principes-clés des 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.

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 :

  • Inventer des noms en l'air
  • Ignorer tous les travaux précédents
  • Hostilité véritable envers les noms/termes provenant d'autres standards
  • Utiliser les noms des autres pour signifier des choses différentes
  • Utiliser de nouveaux noms pour signifier la même chose
  • Débattre sans fin et "forger-des-noms" afin de parvenir à un nom légèrement plus parfait.

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.

Malheureusement, un tel désire pour la nouveauté est mauvais pour les standards, et certainement mauvais pour l'interopérabilité, qui dépend d'être capable de compter surle 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).

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

Avec l'expérience de développer de nouveaux microformats tels que xFolk, hReview et 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 et hCalendar, et c'est l'intention de ce document.

Table des Matières

Auteur

(traduction en cours User:ChristopheDucamp


Principes de Design XHTML Sémantique

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.

Note : les Principes de Design XHTML Sémantique ont été écrits initialement dans le contexte de développement de hCard et hCalendar, par conséquent il peut être plus facile de comprendre ces principes dans le contexte de la méthodologie de design hCard (ce qui veut dire, lisez ça d'abord). Tantek

XHTML est construit sur du XML, et par conséquent les formats fondés sur XHTML peuvent être utilisés non seulement pour une présentation d'affichage pratique, mais aussi à des fins d'échanges de données. A bien des façons, les formats fondés sur XHTML illustrent le meilleur des mondes tant du HTML que du XML. Néanmoins au moment de construire des formats basés sur XHTML, cela aide d'avoir un ensemble de principes directeurs.

  1. Réutilisez autant que possible le schéma (noms, objets, propriétés, valeurs, types, hiérarchies, contraintes) à partir des standards de référence établis et bien supportés. Evitez de redéclarer les contraintes exprimées dans le standard source. Des mentions à titre d'information peuvent passer.
    1. Pour les types avec plusieurs composants, utilisez des éléments imbriqués avec des noms de classe équivalents aux noms des composants.
    2. Les composants pluriels sont produits au singulier, et par conséquent plusieurs éléments imbriqués sont utilisés pour représenter plusieurs valeurs de texte qui sont délimitées par des virgules.
  2. Utilisez la sémantique XHTML la plus précise pour construire des blocs pour chaque objet, etc.
  3. Autrement utilisez un élément générique structurel (par ex. <span> ou <div>), ou l'élément contextuel approprié (par ex. un <li> dans un <ul> ou <ol>).
  4. Utilisez des noms de classes basés sur des noms extraits du schéma original, à moins que le XHTML sémantique de construction de bloc ne représente précisément cette partie du schéma original. Si les noms dans le schéma original ne sont pas sensibles la casse, alors mettez tout dans un équivalent en bas de casse. Les noms de composants implicites en prose (plutôt qu'explicites dans le schéma défini) devraient aussi utiliser les équivalents bas de casse pour une facilité d'utilisation. Les espaces dans les noms des composants deviennent des caractères tiret '-'.
  5. Pour finir, si le format de la donnée selon le schéma original est trop long et/ou non amical sur le plan humain, utilisez <abbr> au lieu d'un élément générique structurel, et placez les données littérales dans l'attribut 'title' (là où vont les expansions abbr), et l'équivalent le plus bref et le plus lisible humainement dans l'élément lui-même. De plus amples explications de cet usage de <abbr> : Human vs. ISO8601 dates problem solved

Quelques Détails

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

Noms de Classe Racine Uniques

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.

Vocabulaire Minimal

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.

Réutilisaton des Microformats en Premier, Autres Standards en 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).

Pour les Autres Standards, Préférez les Plus Vieux aux Plus Récents

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.

Exemples pour suivre les Conventions de Nommage

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.

Modèles de Nommage en Considération en tant que Principes

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.

propriétés dt

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 avec le préfixe dt

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:

En rapport :