From f6f0c1509a262eb9a5e7bd5d1a84a7b24551eee6 Mon Sep 17 00:00:00 2001 From: julieng Date: Thu, 11 Nov 2021 06:45:13 +0100 Subject: move *.html to *.md --- .../mdn/guidelines/code_guidelines/css/index.html | 255 ----------- .../fr/mdn/guidelines/code_guidelines/css/index.md | 255 +++++++++++ .../guidelines/code_guidelines/general/index.html | 167 ------- .../guidelines/code_guidelines/general/index.md | 167 +++++++ .../mdn/guidelines/code_guidelines/html/index.html | 162 ------- .../mdn/guidelines/code_guidelines/html/index.md | 162 +++++++ files/fr/mdn/guidelines/code_guidelines/index.html | 64 --- files/fr/mdn/guidelines/code_guidelines/index.md | 64 +++ .../code_guidelines/javascript/index.html | 501 --------------------- .../guidelines/code_guidelines/javascript/index.md | 501 +++++++++++++++++++++ .../guidelines/code_guidelines/shell/index.html | 37 -- .../mdn/guidelines/code_guidelines/shell/index.md | 37 ++ .../guidelines/conventions_definitions/index.html | 175 ------- .../guidelines/conventions_definitions/index.md | 175 +++++++ .../guidelines/does_this_belong_on_mdn/index.html | 87 ---- .../guidelines/does_this_belong_on_mdn/index.md | 87 ++++ files/fr/mdn/guidelines/editorial/index.html | 37 -- files/fr/mdn/guidelines/editorial/index.md | 37 ++ files/fr/mdn/guidelines/index.html | 14 - files/fr/mdn/guidelines/index.md | 14 + files/fr/mdn/guidelines/video/index.html | 230 ---------- files/fr/mdn/guidelines/video/index.md | 230 ++++++++++ .../mdn/guidelines/writing_style_guide/index.html | 124 ----- .../fr/mdn/guidelines/writing_style_guide/index.md | 124 +++++ 24 files changed, 1853 insertions(+), 1853 deletions(-) delete mode 100644 files/fr/mdn/guidelines/code_guidelines/css/index.html create mode 100644 files/fr/mdn/guidelines/code_guidelines/css/index.md delete mode 100644 files/fr/mdn/guidelines/code_guidelines/general/index.html create mode 100644 files/fr/mdn/guidelines/code_guidelines/general/index.md delete mode 100644 files/fr/mdn/guidelines/code_guidelines/html/index.html create mode 100644 files/fr/mdn/guidelines/code_guidelines/html/index.md delete mode 100644 files/fr/mdn/guidelines/code_guidelines/index.html create mode 100644 files/fr/mdn/guidelines/code_guidelines/index.md delete mode 100644 files/fr/mdn/guidelines/code_guidelines/javascript/index.html create mode 100644 files/fr/mdn/guidelines/code_guidelines/javascript/index.md delete mode 100644 files/fr/mdn/guidelines/code_guidelines/shell/index.html create mode 100644 files/fr/mdn/guidelines/code_guidelines/shell/index.md delete mode 100644 files/fr/mdn/guidelines/conventions_definitions/index.html create mode 100644 files/fr/mdn/guidelines/conventions_definitions/index.md delete mode 100644 files/fr/mdn/guidelines/does_this_belong_on_mdn/index.html create mode 100644 files/fr/mdn/guidelines/does_this_belong_on_mdn/index.md delete mode 100644 files/fr/mdn/guidelines/editorial/index.html create mode 100644 files/fr/mdn/guidelines/editorial/index.md delete mode 100644 files/fr/mdn/guidelines/index.html create mode 100644 files/fr/mdn/guidelines/index.md delete mode 100644 files/fr/mdn/guidelines/video/index.html create mode 100644 files/fr/mdn/guidelines/video/index.md delete mode 100644 files/fr/mdn/guidelines/writing_style_guide/index.html create mode 100644 files/fr/mdn/guidelines/writing_style_guide/index.md (limited to 'files/fr/mdn/guidelines') diff --git a/files/fr/mdn/guidelines/code_guidelines/css/index.html b/files/fr/mdn/guidelines/code_guidelines/css/index.html deleted file mode 100644 index 2e2a768762..0000000000 --- a/files/fr/mdn/guidelines/code_guidelines/css/index.html +++ /dev/null @@ -1,255 +0,0 @@ ---- -title: Lignes directrices du CSS -slug: MDN/Guidelines/Code_guidelines/CSS -tags: - - CSS - - Code - - Guide - - Directives - - MDN Meta -translation_of: MDN/Guidelines/Code_guidelines/CSS ---- -
{{MDNSidebar}}
- -

Les directives suivantes couvrent la manière d'écrire les CSS pour les exemples de code MDN.

- -

Dans cet article

- - - -

Lignes directrices de haut niveau

- -

N'utilisez pas de préprocesseurs

- -

N'utilisez pas la syntaxe des préprocesseurs, ex. Sass, Less, ou Stylus, dans votre code d'exemple MDN. MDN documente le langage CSS classique, et l'utilisation de préprocesseurs ne sert qu'à élever la barre pour comprendre les exemples, ce qui peut potentiellement perdre les lecteurs.

- -

N'utilisez pas de méthodologies CSS spécifiques

- -

Dans le même esprit que la directive précédente, n'écrivez pas de code d'exemple MDN en utilisant une méthodologie CSS spécifique telle que BEM ou SMACSS. Même s'il s'agit de syntaxe CSS valide, les conventions de dénomination peuvent prêter à confusion pour les personnes qui ne sont pas familières avec ces méthodologies.

- -

Utiliser des unités flexibles/relatives

- -

Pour une flexibilité maximale sur le plus grand nombre possible d'appareils, il est judicieux de dimensionner les conteneurs, le padding, etc. en utilisant des unités relatives comme les em et les rem, ou des pourcentages et des unités de « viewport » si vous souhaitez qu'ils varient en fonction de la largeur du « viewport ». Vous pouvez en savoir plus à ce sujet dans notre article Éléments de construction d'un design adaptatif (Responsive Design).

- -

Ne pas utiliser de réinitialisation

- -

Pour un contrôle maximal des CSS sur toutes les plates-formes, beaucoup de gens avaient l'habitude d'utiliser les réinitialisations CSS pour supprimer tous les styles, avant de reconstruire les choses eux-mêmes. Cette méthode a certainement ses mérites, mais surtout dans le monde moderne, les réinitialisations CSS peuvent être excessives et entraîner beaucoup de temps supplémentaire passé à réimplémenter des choses qui n'étaient pas complètement cassées au départ, comme les marges par défaut, les styles de liste, etc.

- -

Si vous avez vraiment envie d'utiliser une réinitialisation, envisagez d'utiliser normalize.css de Nicolas Gallagher, qui vise simplement à rendre les choses plus cohérentes d'un navigateur à l'autre, à se débarrasser de certains désagréments par défaut que nous supprimons toujours (les marges sur <body>, par exemple) et à corriger quelques bogues.

- -

Planifiez votre CSS — évitez les surcharges

- -

Avant de vous lancer dans l'écriture de gros morceaux de CSS, planifiez soigneusement vos styles. Quels styles généraux seront nécessaires, quelles mises en page différentes devrez-vous créer, quelles redéfinitions spécifiques devront être créées et seront-elles réutilisables ? Par-dessus tout, vous devez essayer d'éviter de créer trop de redéfinitions. Si vous vous retrouvez constamment en train d'écrire des styles pour ensuite les annuler quelques règles plus bas, vous devez probablement repenser votre stratégie.

- -

Style général de codage CSS

- -

Utiliser une syntaxe étendue

- -

Vous pouvez utiliser différents styles d'écriture CSS, mais nous préférons le style étendu, avec le sélecteur/l'accolade ouvrante, l'accolade fermante et chaque déclaration sur une ligne distincte. Cela optimise la lisibilité et favorise la cohérence sur le MDN.

- -

Utilisez ceci :

- -
p {
-  color: white;
-  background-color: black;
-  padding: 1rem;
-}
- -

Pas cela :

- -
p { color: white; background-color: black; padding: 1rem; }
- -

En outre, gardez ces spécificités à l'esprit :

- - - -

Privilégiez les règles longues aux règles raccourcies

- -

En général, lorsque vous enseignez les spécificités de la syntaxe CSS, il est plus clair et plus évident d'utiliser des propriétés longues plutôt que des raccourcies (à moins bien sûr que l'enseignement du raccourci ne soit le but de l'exemple). N'oubliez pas que les exemples du MDN ont pour but d'enseigner aux gens, et non d'être efficaces ou astucieuses.

- -

Tout d'abord, il est souvent plus difficile de comprendre ce que fait le raccourci. Il faut un certain temps pour comprendre exactement ce que fait la syntaxe font, par exemple :

- -
font: small-caps bold 2rem/1.5 sans-serif;
- -

Alors que celle-ci est plus immédiate en termes de compréhension :

- -
font-variant: small-caps;
-font-weight: bold;
-font-size: 2rem;
-line-height: 1.5;
-font-family: sans-serif;
- -

Deuxièmement, les raccourcis CSS comportent des pièges potentiels supplémentaires : des valeurs par défaut sont définies pour des parties de la syntaxe que vous n'avez pas explicitement définies, ce qui peut produire des réinitialisations inattendues des valeurs que vous avez définies plus tôt dans la cascade, ou d'autres effets attendus. Par exemple, la propriété grid définit toutes les valeurs par défaut suivantes pour les éléments qui ne sont pas spécifiés :

- - - -

En outre, certains raccourcis ne fonctionnent comme prévu que si vous incluez les différents composants de la valeur dans un certain ordre. Dans les animations CSS, par exemple :

- -
/* duration | timing-function | delay | iteration-count
-   direction | fill-mode | play-state | name */
-animation: 3s ease-in 1s 2 reverse both paused slidein;
- -

À titre d'exemple, la première valeur qui peut être analysée comme un <time> est affecté à la propriété animation-duration, et la seconde est affectée à animation-delay. Pour plus de détails, lisez l'intégralité de syntaxe de l'animation.

- -

Utilisez des guillemets doubles autour des valeurs

- -

Lorsque des guillemets peuvent ou doivent être inclus, utilisez-les, et utilisez des guillemets doubles. Par exemple :

- -
[data-vegetable="liquid"] {
-  background-color: goldenrod;
-  background-image: url("../../media/examples/lizard.png");
-}
- -

Espacement autour des paramètres de la fonction

- -

Les paramètres des fonctions doivent comporter des espaces après les virgules de séparation, mais pas avant :

- -
color: rgb(255, 0, 0);
-background-image: linear-gradient(to bottom, red, black);
- -

Commentaires CSS

- -

Utilisez des commentaires de style CSS pour commenter le code qui n'est pas auto-documenté :

- -
/* Il s'agit d'un commentaire de style CSS */
- -

Mettez vos commentaires sur des lignes séparées précédant le code auquel ils se réfèrent :

- -
h3 {
-  /* Crée une ombre portée rouge, décalée de 1px vers la droite et le bas, avec un rayon de flou de 2px. */
-  text-shadow: 1px 1px 2px red;
-  /* Définit la taille de la police au double de la taille de la police du document par défaut. */
-  font-size: 2rem;
-}
- -

Notez également que vous devez laisser un espace entre les astérisques et le commentaire, dans chaque cas.

- -

Ne pas utiliser !important

- -

!important est un dernier recours généralement utilisé uniquement lorsque vous devez remplacer quelque chose et qu'il n'y a pas d'autre moyen. Il s'agit d'une mauvaise pratique que vous devez éviter dans la mesure du possible.

- -

Mauvais usage :

- -
.bad-code {
-  font-size: 4rem !important;
-}
- -

Points de syntaxe CSS spécifiques

- -

Désactiver les bordures et autres propriétés

- -

Lorsque vous désactivez les bordures (et toute autre propriété qui peut prendre 0 ou none comme valeurs), utilisez 0 plutôt que none :

- -
border: 0;
- -

Utilisez des requêtes média "mobile first"

- -

Lorsque vous incluez différents ensembles de styles pour différentes tailles de fenêtres d'affichage à l'aide de requêtes de médias dans la même feuille de style, il est judicieux de faire en sorte que le style par défaut avant l'application de toute requête de médias au document soit le style pour écran étroit/mobile, puis de le remplacer pour les fenêtres d'affichage plus larges dans des requêtes de médias successives.

- -
/* Mise en page CSS par défaut pour les écrans étroits */
-
-@media (min-width: 480px) {
-  /* CSS pour les écrans de largeur moyenne */
-}
-
-@media (min-width: 800px) {
-  /* CSS pour les écrans larges */
-}
-
-@media (min-width: 1100px) {
-  /* CSS pour les écrans très larges */
-}
- -

Cela présente de nombreux avantages, exposés dans notre article Priorité aux mobiles.

- -

Sélecteurs

- -

N'utilisez pas de sélecteurs ID

- -

Il n'est pas vraiment nécessaire d'utiliser des sélecteurs d'ID - ils sont moins flexibles (vous ne pouvez pas en ajouter d'autres si vous découvrez que vous en avez besoin de plus d'un), et il est plus difficile de les remplacer si nécessaire, car ils sont plus spécifiques que les classes.

- -

Bonne pratique :

- -
.editorial-summary {
-  ...
-}
- -

Mauvaise pratique :

- -
#editorial-summary {
-  ...
-}
- -

Mettre les sélecteurs multiples sur des lignes séparées

- -

Lorsqu'une règle comporte plusieurs sélecteurs, placez chaque sélecteur sur une nouvelle ligne. La liste des sélecteurs est ainsi plus facile à lire et les lignes de code sont plus courtes.

- -

Faites ceci :

- -
h1,
-h2,
-h3 {
-  font-family: sans-serif;
-  text-align: center;
-}
- -

Pas ça :

- -
h1, h2, h3 {
-  font-family: sans-serif;
-  text-align: center;
-}
- -

De bons exemples de CSS sur MDN

- -

Vous pouvez trouver de bons extraits CSS concis et significatifs en haut de nos pages de référence des propriétés CSS - parcourez notre index des mots-clés CSS pour en trouver. Nos exemples interactifs sont généralement écrits pour suivre les directives ci-dessus, mais sachez qu'ils peuvent différer à certains endroits, car ils ont pour la plupart été écrits avant la nouvelle rédaction des directives.

diff --git a/files/fr/mdn/guidelines/code_guidelines/css/index.md b/files/fr/mdn/guidelines/code_guidelines/css/index.md new file mode 100644 index 0000000000..2e2a768762 --- /dev/null +++ b/files/fr/mdn/guidelines/code_guidelines/css/index.md @@ -0,0 +1,255 @@ +--- +title: Lignes directrices du CSS +slug: MDN/Guidelines/Code_guidelines/CSS +tags: + - CSS + - Code + - Guide + - Directives + - MDN Meta +translation_of: MDN/Guidelines/Code_guidelines/CSS +--- +
{{MDNSidebar}}
+ +

Les directives suivantes couvrent la manière d'écrire les CSS pour les exemples de code MDN.

+ +

Dans cet article

+ + + +

Lignes directrices de haut niveau

+ +

N'utilisez pas de préprocesseurs

+ +

N'utilisez pas la syntaxe des préprocesseurs, ex. Sass, Less, ou Stylus, dans votre code d'exemple MDN. MDN documente le langage CSS classique, et l'utilisation de préprocesseurs ne sert qu'à élever la barre pour comprendre les exemples, ce qui peut potentiellement perdre les lecteurs.

+ +

N'utilisez pas de méthodologies CSS spécifiques

+ +

Dans le même esprit que la directive précédente, n'écrivez pas de code d'exemple MDN en utilisant une méthodologie CSS spécifique telle que BEM ou SMACSS. Même s'il s'agit de syntaxe CSS valide, les conventions de dénomination peuvent prêter à confusion pour les personnes qui ne sont pas familières avec ces méthodologies.

+ +

Utiliser des unités flexibles/relatives

+ +

Pour une flexibilité maximale sur le plus grand nombre possible d'appareils, il est judicieux de dimensionner les conteneurs, le padding, etc. en utilisant des unités relatives comme les em et les rem, ou des pourcentages et des unités de « viewport » si vous souhaitez qu'ils varient en fonction de la largeur du « viewport ». Vous pouvez en savoir plus à ce sujet dans notre article Éléments de construction d'un design adaptatif (Responsive Design).

+ +

Ne pas utiliser de réinitialisation

+ +

Pour un contrôle maximal des CSS sur toutes les plates-formes, beaucoup de gens avaient l'habitude d'utiliser les réinitialisations CSS pour supprimer tous les styles, avant de reconstruire les choses eux-mêmes. Cette méthode a certainement ses mérites, mais surtout dans le monde moderne, les réinitialisations CSS peuvent être excessives et entraîner beaucoup de temps supplémentaire passé à réimplémenter des choses qui n'étaient pas complètement cassées au départ, comme les marges par défaut, les styles de liste, etc.

+ +

Si vous avez vraiment envie d'utiliser une réinitialisation, envisagez d'utiliser normalize.css de Nicolas Gallagher, qui vise simplement à rendre les choses plus cohérentes d'un navigateur à l'autre, à se débarrasser de certains désagréments par défaut que nous supprimons toujours (les marges sur <body>, par exemple) et à corriger quelques bogues.

+ +

Planifiez votre CSS — évitez les surcharges

+ +

Avant de vous lancer dans l'écriture de gros morceaux de CSS, planifiez soigneusement vos styles. Quels styles généraux seront nécessaires, quelles mises en page différentes devrez-vous créer, quelles redéfinitions spécifiques devront être créées et seront-elles réutilisables ? Par-dessus tout, vous devez essayer d'éviter de créer trop de redéfinitions. Si vous vous retrouvez constamment en train d'écrire des styles pour ensuite les annuler quelques règles plus bas, vous devez probablement repenser votre stratégie.

+ +

Style général de codage CSS

+ +

Utiliser une syntaxe étendue

+ +

Vous pouvez utiliser différents styles d'écriture CSS, mais nous préférons le style étendu, avec le sélecteur/l'accolade ouvrante, l'accolade fermante et chaque déclaration sur une ligne distincte. Cela optimise la lisibilité et favorise la cohérence sur le MDN.

+ +

Utilisez ceci :

+ +
p {
+  color: white;
+  background-color: black;
+  padding: 1rem;
+}
+ +

Pas cela :

+ +
p { color: white; background-color: black; padding: 1rem; }
+ +

En outre, gardez ces spécificités à l'esprit :

+ + + +

Privilégiez les règles longues aux règles raccourcies

+ +

En général, lorsque vous enseignez les spécificités de la syntaxe CSS, il est plus clair et plus évident d'utiliser des propriétés longues plutôt que des raccourcies (à moins bien sûr que l'enseignement du raccourci ne soit le but de l'exemple). N'oubliez pas que les exemples du MDN ont pour but d'enseigner aux gens, et non d'être efficaces ou astucieuses.

+ +

Tout d'abord, il est souvent plus difficile de comprendre ce que fait le raccourci. Il faut un certain temps pour comprendre exactement ce que fait la syntaxe font, par exemple :

+ +
font: small-caps bold 2rem/1.5 sans-serif;
+ +

Alors que celle-ci est plus immédiate en termes de compréhension :

+ +
font-variant: small-caps;
+font-weight: bold;
+font-size: 2rem;
+line-height: 1.5;
+font-family: sans-serif;
+ +

Deuxièmement, les raccourcis CSS comportent des pièges potentiels supplémentaires : des valeurs par défaut sont définies pour des parties de la syntaxe que vous n'avez pas explicitement définies, ce qui peut produire des réinitialisations inattendues des valeurs que vous avez définies plus tôt dans la cascade, ou d'autres effets attendus. Par exemple, la propriété grid définit toutes les valeurs par défaut suivantes pour les éléments qui ne sont pas spécifiés :

+ + + +

En outre, certains raccourcis ne fonctionnent comme prévu que si vous incluez les différents composants de la valeur dans un certain ordre. Dans les animations CSS, par exemple :

+ +
/* duration | timing-function | delay | iteration-count
+   direction | fill-mode | play-state | name */
+animation: 3s ease-in 1s 2 reverse both paused slidein;
+ +

À titre d'exemple, la première valeur qui peut être analysée comme un <time> est affecté à la propriété animation-duration, et la seconde est affectée à animation-delay. Pour plus de détails, lisez l'intégralité de syntaxe de l'animation.

+ +

Utilisez des guillemets doubles autour des valeurs

+ +

Lorsque des guillemets peuvent ou doivent être inclus, utilisez-les, et utilisez des guillemets doubles. Par exemple :

+ +
[data-vegetable="liquid"] {
+  background-color: goldenrod;
+  background-image: url("../../media/examples/lizard.png");
+}
+ +

Espacement autour des paramètres de la fonction

+ +

Les paramètres des fonctions doivent comporter des espaces après les virgules de séparation, mais pas avant :

+ +
color: rgb(255, 0, 0);
+background-image: linear-gradient(to bottom, red, black);
+ +

Commentaires CSS

+ +

Utilisez des commentaires de style CSS pour commenter le code qui n'est pas auto-documenté :

+ +
/* Il s'agit d'un commentaire de style CSS */
+ +

Mettez vos commentaires sur des lignes séparées précédant le code auquel ils se réfèrent :

+ +
h3 {
+  /* Crée une ombre portée rouge, décalée de 1px vers la droite et le bas, avec un rayon de flou de 2px. */
+  text-shadow: 1px 1px 2px red;
+  /* Définit la taille de la police au double de la taille de la police du document par défaut. */
+  font-size: 2rem;
+}
+ +

Notez également que vous devez laisser un espace entre les astérisques et le commentaire, dans chaque cas.

+ +

Ne pas utiliser !important

+ +

!important est un dernier recours généralement utilisé uniquement lorsque vous devez remplacer quelque chose et qu'il n'y a pas d'autre moyen. Il s'agit d'une mauvaise pratique que vous devez éviter dans la mesure du possible.

+ +

Mauvais usage :

+ +
.bad-code {
+  font-size: 4rem !important;
+}
+ +

Points de syntaxe CSS spécifiques

+ +

Désactiver les bordures et autres propriétés

+ +

Lorsque vous désactivez les bordures (et toute autre propriété qui peut prendre 0 ou none comme valeurs), utilisez 0 plutôt que none :

+ +
border: 0;
+ +

Utilisez des requêtes média "mobile first"

+ +

Lorsque vous incluez différents ensembles de styles pour différentes tailles de fenêtres d'affichage à l'aide de requêtes de médias dans la même feuille de style, il est judicieux de faire en sorte que le style par défaut avant l'application de toute requête de médias au document soit le style pour écran étroit/mobile, puis de le remplacer pour les fenêtres d'affichage plus larges dans des requêtes de médias successives.

+ +
/* Mise en page CSS par défaut pour les écrans étroits */
+
+@media (min-width: 480px) {
+  /* CSS pour les écrans de largeur moyenne */
+}
+
+@media (min-width: 800px) {
+  /* CSS pour les écrans larges */
+}
+
+@media (min-width: 1100px) {
+  /* CSS pour les écrans très larges */
+}
+ +

Cela présente de nombreux avantages, exposés dans notre article Priorité aux mobiles.

+ +

Sélecteurs

+ +

N'utilisez pas de sélecteurs ID

+ +

Il n'est pas vraiment nécessaire d'utiliser des sélecteurs d'ID - ils sont moins flexibles (vous ne pouvez pas en ajouter d'autres si vous découvrez que vous en avez besoin de plus d'un), et il est plus difficile de les remplacer si nécessaire, car ils sont plus spécifiques que les classes.

+ +

Bonne pratique :

+ +
.editorial-summary {
+  ...
+}
+ +

Mauvaise pratique :

+ +
#editorial-summary {
+  ...
+}
+ +

Mettre les sélecteurs multiples sur des lignes séparées

+ +

Lorsqu'une règle comporte plusieurs sélecteurs, placez chaque sélecteur sur une nouvelle ligne. La liste des sélecteurs est ainsi plus facile à lire et les lignes de code sont plus courtes.

+ +

Faites ceci :

+ +
h1,
+h2,
+h3 {
+  font-family: sans-serif;
+  text-align: center;
+}
+ +

Pas ça :

+ +
h1, h2, h3 {
+  font-family: sans-serif;
+  text-align: center;
+}
+ +

De bons exemples de CSS sur MDN

+ +

Vous pouvez trouver de bons extraits CSS concis et significatifs en haut de nos pages de référence des propriétés CSS - parcourez notre index des mots-clés CSS pour en trouver. Nos exemples interactifs sont généralement écrits pour suivre les directives ci-dessus, mais sachez qu'ils peuvent différer à certains endroits, car ils ont pour la plupart été écrits avant la nouvelle rédaction des directives.

diff --git a/files/fr/mdn/guidelines/code_guidelines/general/index.html b/files/fr/mdn/guidelines/code_guidelines/general/index.html deleted file mode 100644 index d35985d1aa..0000000000 --- a/files/fr/mdn/guidelines/code_guidelines/general/index.html +++ /dev/null @@ -1,167 +0,0 @@ ---- -title: Lignes directrices générales pour tous les exemples de code -slug: MDN/Guidelines/Code_guidelines/General -tags: - - Code - - General - - Guide - - Directives - - MDN Meta -translation_of: MDN/Guidelines/Code_guidelines/General ---- -
{{MDNSidebar}}
- -

Les directives suivantes concernant les exemples de code s'appliquent à tout le code, qu'il s'agisse de HTML, de CSS, de JavaScript ou d'autre chose.

- -

Dans cet article

- - - -

Indentation, espacement, taille

- -

Indentation

- -

Tout le code doit utiliser 2 espaces pour l'indentation, par exemple :

- -
<div>
-  <p>C'est mon paragraphe.</p>
-</div>
- -
function myFunc() {
-  if(thingy) {
-    console.log('Ouaip, ça a marché.');
-  }
-}
- -

Longueur des lignes de code

- -

Les lignes de code ne doivent pas comporter plus de 80 caractères (64 pour les exemples interactifs). Vous devez rompre les lignes de manière raisonnable pour des raisons de lisibilité, mais pas au détriment des bonnes pratiques.

- -

Par exemple, ceci n'est pas génial :

- -
let tommyCat = 'Dit Tommy le chat en reculant pour évacuer tout corps étranger qui aurait pu se loger dans sa puissante gorge. Plus d'un gros rat de gouttière avait trouvé la mort en regardant à bout portant le canon caverneux de cette impressionnante machine à rôder.';
- -

C'est mieux, mais un peu gênant :

- -
let tommyCat = 'Dit Tommy le chat en reculant pour évacuer tout corps étranger '
-+ 'qui aurait pu se loger dans sa puissante gorge. Plus d’un gros rat de gouttière '
-+ 'avait trouvé la mort en regardant à bout portant le canon caverneux de cette '
-+ 'impressionnante machine à rôder.';
- -

Une meilleure solution consiste à utiliser un template :

- -
let tommyCat = `Dit Tommy le chat en reculant pour évacuer tout corps étranger
-  qui aurait pu se loger dans sa puissante gorge. Plus d'un gros rat de gouttière
-  avait trouvé la mort en regardant à bout portant le canon caverneux de cette
-  impressionnante machine à rôder.`;
- -

Hauteur des blocs de code

- -

Les blocs de code doivent être aussi longs que nécessaire, mais pas plus. L'idéal est de viser quelque chose de court, comme 15 à 25 lignes. Si un bloc de code doit être beaucoup plus long, envisagez de ne montrer que l'extrait le plus utile et de créer un lien vers l'exemple complet sur un repo GitHub ou un CodePen, par exemple.

- -

Directives pour l'affichage des exemples

- -

Taille du rendu des exemples

- -

Le volet de contenu principal de MDN a une largeur d'environ 700px sur un ordinateur de bureau. Les exemples intégrés à MDN doivent donc avoir une apparence correcte à cette largeur (définissez la largeur des exemples intégrés à 100%).

- -

En ce qui concerne la hauteur, nous vous recommandons de maintenir l'exemple rendu à moins de 700px de hauteur si possible, pour une lisibilité maximale à l'écran.

- -

Vous devriez également penser à rendre vos exemples plus ou moins adaptables, afin qu'ils soient également utiles sur les appareils mobiles.

- -

Utilisation d'images et d'autres médias

- -

Parfois, vous voudrez inclure des images ou d'autres médias dans un exemple. Si vous le faites :

- - - -

Utilisation de la couleur

- -

Minuscule pour l'hexadécimal, peut utiliser des mots-clés pour les nuances et les couleurs primaires (ex. : black, white, red), utiliser des schémas plus complexes uniquement si nécessaire (ex. : pour inclure la transparence).

- -

Préférez utiliser des mots-clés pour les couleurs primaires et autres couleurs "de base", par exemple :

- -
-color: black;
-color: white;
-color: red;
-
- -

Utilisez rgb() pour des couleurs plus complexes (y compris les couleurs semi-transparentes) :

- -
-color: rgb(0, 0, 0, 0.5);
-color: rgb(248, 242, 230);
-
- -

Si vous devez utiliser des couleurs hexadécimales, utilisez des minuscules :

- -
-color: #058ed9;
-color: #a39a92;
-
- -

et utilisez la forme abrégée le cas échéant :

- -
-color: #ff0;
-color: #fff;
-
- -

Le fichier sass/vars/_color-palette.scss du dépôt mdn-minimalist comporte un ensemble de couleurs utiles qui complètent le design général de MDN.

- -

Mettre en évidence les exemples de bonnes et de mauvaises pratiques

- -

Comme vous le remarquerez en parcourant ces lignes directrices, les blocs de code censés être des exemples de bonnes pratiques sont marqués d'un fond en vert, et les blocs de code censés être des exemples de mauvaises pratiques sont marqués d'un fond en rouge.

- -

Pour ce faire, vous devez d'abord utiliser les commandes de l'éditeur MDN pour placer votre bloc de code dans un bloc <pre> et lui donner la coloration syntaxique appropriée. La source du code ressemblera à quelque chose comme ceci :

- -
-function myFunc() {
-  console.log('Hello!');
-};
-</pre>
-
- -

Pour en faire un bon exemple, vous insérez example-good juste avant le guillemet fermant de l'attribut class :

- -
<pre class="brush: js example-good">
-  ...
-
- -

Pour en faire un mauvais exemple, vous insérez example-bad juste avant le guillemet fermant de l'attribut class :

- -
<pre class="brush: js example-bad">
-  ...
-
- -

Nous aimerions vous encourager à les utiliser. Il n'est pas nécessaire de les utiliser partout, mais seulement lorsque vous signalez spécifiquement les bonnes et mauvaises pratiques dans votre code.

- -

Rédaction de sections syntaxiques sur les pages de référence

- -

Les pages de référence MDN comprennent des sections Syntaxe qui indiquent sans ambiguïté quelle peut/doit être la syntaxe d'une fonctionnalité, par exemple une méthode JavaScript, une propriété CSS, un élément HTML, etc. Des directives pour les rédiger sont données sur le document Sections syntaxiques.

diff --git a/files/fr/mdn/guidelines/code_guidelines/general/index.md b/files/fr/mdn/guidelines/code_guidelines/general/index.md new file mode 100644 index 0000000000..d35985d1aa --- /dev/null +++ b/files/fr/mdn/guidelines/code_guidelines/general/index.md @@ -0,0 +1,167 @@ +--- +title: Lignes directrices générales pour tous les exemples de code +slug: MDN/Guidelines/Code_guidelines/General +tags: + - Code + - General + - Guide + - Directives + - MDN Meta +translation_of: MDN/Guidelines/Code_guidelines/General +--- +
{{MDNSidebar}}
+ +

Les directives suivantes concernant les exemples de code s'appliquent à tout le code, qu'il s'agisse de HTML, de CSS, de JavaScript ou d'autre chose.

+ +

Dans cet article

+ + + +

Indentation, espacement, taille

+ +

Indentation

+ +

Tout le code doit utiliser 2 espaces pour l'indentation, par exemple :

+ +
<div>
+  <p>C'est mon paragraphe.</p>
+</div>
+ +
function myFunc() {
+  if(thingy) {
+    console.log('Ouaip, ça a marché.');
+  }
+}
+ +

Longueur des lignes de code

+ +

Les lignes de code ne doivent pas comporter plus de 80 caractères (64 pour les exemples interactifs). Vous devez rompre les lignes de manière raisonnable pour des raisons de lisibilité, mais pas au détriment des bonnes pratiques.

+ +

Par exemple, ceci n'est pas génial :

+ +
let tommyCat = 'Dit Tommy le chat en reculant pour évacuer tout corps étranger qui aurait pu se loger dans sa puissante gorge. Plus d'un gros rat de gouttière avait trouvé la mort en regardant à bout portant le canon caverneux de cette impressionnante machine à rôder.';
+ +

C'est mieux, mais un peu gênant :

+ +
let tommyCat = 'Dit Tommy le chat en reculant pour évacuer tout corps étranger '
++ 'qui aurait pu se loger dans sa puissante gorge. Plus d’un gros rat de gouttière '
++ 'avait trouvé la mort en regardant à bout portant le canon caverneux de cette '
++ 'impressionnante machine à rôder.';
+ +

Une meilleure solution consiste à utiliser un template :

+ +
let tommyCat = `Dit Tommy le chat en reculant pour évacuer tout corps étranger
+  qui aurait pu se loger dans sa puissante gorge. Plus d'un gros rat de gouttière
+  avait trouvé la mort en regardant à bout portant le canon caverneux de cette
+  impressionnante machine à rôder.`;
+ +

Hauteur des blocs de code

+ +

Les blocs de code doivent être aussi longs que nécessaire, mais pas plus. L'idéal est de viser quelque chose de court, comme 15 à 25 lignes. Si un bloc de code doit être beaucoup plus long, envisagez de ne montrer que l'extrait le plus utile et de créer un lien vers l'exemple complet sur un repo GitHub ou un CodePen, par exemple.

+ +

Directives pour l'affichage des exemples

+ +

Taille du rendu des exemples

+ +

Le volet de contenu principal de MDN a une largeur d'environ 700px sur un ordinateur de bureau. Les exemples intégrés à MDN doivent donc avoir une apparence correcte à cette largeur (définissez la largeur des exemples intégrés à 100%).

+ +

En ce qui concerne la hauteur, nous vous recommandons de maintenir l'exemple rendu à moins de 700px de hauteur si possible, pour une lisibilité maximale à l'écran.

+ +

Vous devriez également penser à rendre vos exemples plus ou moins adaptables, afin qu'ils soient également utiles sur les appareils mobiles.

+ +

Utilisation d'images et d'autres médias

+ +

Parfois, vous voudrez inclure des images ou d'autres médias dans un exemple. Si vous le faites :

+ + + +

Utilisation de la couleur

+ +

Minuscule pour l'hexadécimal, peut utiliser des mots-clés pour les nuances et les couleurs primaires (ex. : black, white, red), utiliser des schémas plus complexes uniquement si nécessaire (ex. : pour inclure la transparence).

+ +

Préférez utiliser des mots-clés pour les couleurs primaires et autres couleurs "de base", par exemple :

+ +
+color: black;
+color: white;
+color: red;
+
+ +

Utilisez rgb() pour des couleurs plus complexes (y compris les couleurs semi-transparentes) :

+ +
+color: rgb(0, 0, 0, 0.5);
+color: rgb(248, 242, 230);
+
+ +

Si vous devez utiliser des couleurs hexadécimales, utilisez des minuscules :

+ +
+color: #058ed9;
+color: #a39a92;
+
+ +

et utilisez la forme abrégée le cas échéant :

+ +
+color: #ff0;
+color: #fff;
+
+ +

Le fichier sass/vars/_color-palette.scss du dépôt mdn-minimalist comporte un ensemble de couleurs utiles qui complètent le design général de MDN.

+ +

Mettre en évidence les exemples de bonnes et de mauvaises pratiques

+ +

Comme vous le remarquerez en parcourant ces lignes directrices, les blocs de code censés être des exemples de bonnes pratiques sont marqués d'un fond en vert, et les blocs de code censés être des exemples de mauvaises pratiques sont marqués d'un fond en rouge.

+ +

Pour ce faire, vous devez d'abord utiliser les commandes de l'éditeur MDN pour placer votre bloc de code dans un bloc <pre> et lui donner la coloration syntaxique appropriée. La source du code ressemblera à quelque chose comme ceci :

+ +
+function myFunc() {
+  console.log('Hello!');
+};
+</pre>
+
+ +

Pour en faire un bon exemple, vous insérez example-good juste avant le guillemet fermant de l'attribut class :

+ +
<pre class="brush: js example-good">
+  ...
+
+ +

Pour en faire un mauvais exemple, vous insérez example-bad juste avant le guillemet fermant de l'attribut class :

+ +
<pre class="brush: js example-bad">
+  ...
+
+ +

Nous aimerions vous encourager à les utiliser. Il n'est pas nécessaire de les utiliser partout, mais seulement lorsque vous signalez spécifiquement les bonnes et mauvaises pratiques dans votre code.

+ +

Rédaction de sections syntaxiques sur les pages de référence

+ +

Les pages de référence MDN comprennent des sections Syntaxe qui indiquent sans ambiguïté quelle peut/doit être la syntaxe d'une fonctionnalité, par exemple une méthode JavaScript, une propriété CSS, un élément HTML, etc. Des directives pour les rédiger sont données sur le document Sections syntaxiques.

diff --git a/files/fr/mdn/guidelines/code_guidelines/html/index.html b/files/fr/mdn/guidelines/code_guidelines/html/index.html deleted file mode 100644 index 086c1f5e34..0000000000 --- a/files/fr/mdn/guidelines/code_guidelines/html/index.html +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: Lignes directrices pour le HTML -slug: MDN/Guidelines/Code_guidelines/HTML -tags: - - Code - - Guide - - Directives - - HTML - - MDN Meta -translation_of: MDN/Guidelines/Code_guidelines/HTML ---- -
{{MDNSidebar}}
- -

Les directives suivantes couvrent la manière d'écrire du HTML pour les exemples de code MDN.

- -

Dans cet article

- - - -

Doctype et méta-données

- -
-

Note : Les directives de cette section ne s'appliquent que lorsque vous devez montrer un document HTML complet. La plupart du temps, vous n'aurez pas besoin de le faire ; un extrait est généralement suffisant pour démontrer une fonctionnalité. Lorsque vous utilisez la macro EmbedLiveSample, il suffit d'inclure l'extrait HTML ; il sera automatiquement inséré dans un document HTML complet lors de son affichage.

-
- -

Doctype

- -

Vous devez utiliser le doctype HTML5. Il est court, facile à retenir et rétrocompatible :

- -
<!DOCTYPE html>
- -

Langue du document

- -

Définissez la langue du document à l'aide de l'attribut lang de votre élément <html> :

- -
<html lang="fr">
- -

C'est bon pour l'accessibilité et les moteurs de recherche, cela aide à localiser le contenu et cela rappelle aux gens d'utiliser les meilleures pratiques.

- -

Jeu de caractères du document

- -

Vous devez également définir le jeu de caractères de votre document comme suit :

- -
<meta charset="utf-8">
- -

Utilisez UTF-8 à moins que vous n'ayez une très bonne raison de ne pas le faire ; il couvrira vos besoins en caractères à peu près indépendamment de la langue que vous utilisez dans votre document. En outre, vous devriez toujours spécifier le jeu de caractères le plus tôt possible dans le bloc <head> de votre HTML (dans le premier kilooctet), car cela vous protège contre une vulnérabilité de sécurité d'Internet Explorer.

- -

Méta-balise Viewport

- -

Enfin, vous devez toujours ajouter la métabalise viewport dans votre HTML <head>, pour donner à l'exemple une meilleure chance de fonctionner sur les appareils mobiles. Vous devez inclure au moins les éléments suivants dans votre document, que vous pourrez modifier ultérieurement en fonction des besoins :

- -
<meta name="viewport" content="width=device-width">
- -

Voir Zones d'affichage sur mobiles pour plus de détails.

- -

Style général de codage des balises

- -

Utiliser les minuscules

- -

Utilisez les minuscules pour tous les noms d'éléments et les noms/valeurs d'attributs, car elles sont plus nettes et vous permettent d'écrire plus rapidement les balises :

- -

C'est bien :

- -
<p class="nice">Ça a l'air sympa et soigné</p>
- -

Ce n'est pas très bon :

- -
<P CLASS="WHOA-THERE">Pourquoi mon balisage crie-t-il ?</P>
- -

Barre oblique de fermeture (slash)

- -

N'incluez pas les barres obliques de fin de style XHTML pour les éléments vides, car elles sont inutiles et ralentissent le processus. Elles peuvent également casser les anciens navigateurs si vous ne faites pas attention (bien que, d'après ce dont nous nous souvenons, cela n'a pas été un problème depuis Netscape 4).

- -

C'est bon :

- -
<input type="text">
-<hr>
- -

Les barres obliques ne sont pas nécessaires :

- -
<input type="text" />
-<hr />
- -

Guillemets des attributs

- -

Vous devez mettre toutes les valeurs d'attribut entre guillemets. Il est tentant d'omettre les guillemets puisque HTML5 le permet, mais le balisage est plus net et plus facile à lire si vous les incluez. Par exemple, ceci est mieux :

- -
<img src="images/logo.jpg" alt="Une icône de globe circulaire" class="no-border">
- -

que ça :

- -
<img src=images/logo.jpg alt=Une icône de globe circulaire class=no-border>
- -

Cela peut également causer des problèmes - dans l'exemple ci-dessus, l'attribut alt sera interprété comme plusieurs attributs, car il n'y a pas de guillemets pour spécifier que "Une icône de globe circulaire" est une valeur d'attribut unique.

- -

Utiliser les guillemets doubles

- -

Utilisez des guillemets doubles pour le HTML, et non des guillemets simples :

- -
<p class="important">Yes</p>
- -
<p class='important'>Nope</p>
- -

Attributs booléens

- -

N'écrivez pas les attributs booléens en entier ; vous pouvez simplement écrire le nom de l'attribut pour le définir. Par exemple, vous pouvez écrire :

- -
required
- -

Ceci est parfaitement compréhensible et fonctionne bien ; la version plus longue avec la valeur est acceptée mais n'est pas nécessaire :

- -
required="required"
- -

Noms de classes et d'ID

- -

Utilisez des noms de classe/ID sémantiques et séparez les mots multiples par des traits d'union. N'utilisez pas de camelCase.

- -

Bon :

- -
<p class="editorial-summary">Blah blah blah</p>
- -

Mauvais :

- -
<p class="bigRedBox">Blah blah blah</p>
- -

Références des entités

- -

N'utilisez pas inutilement les références d'entités - utilisez le caractère littéral chaque fois que cela est possible (vous devrez toujours échapper les caractères comme les crochets et les guillemets).

- -

Par exemple, vous pourriez simplement écrire

- -
<p>© 2018 Me</p>
- -

Au lieu de

- -
<p>&copy; 2018 Me</p>
- -

Cela ne pose aucun problème tant que vous déclarez un jeu de caractères UTF-8.

- -

De bons exemples HTML sur MDN

- -

Vous pouvez trouver de bons extraits HTML, concis et significatifs, en haut des pages de référence HTML - nos exemples interactifs sont généralement rédigés de manière à suivre ces directives, mais sachez qu'ils peuvent différer à certains endroits car ils ont pour la plupart été rédigés avant la nouvelle rédaction des directives.

diff --git a/files/fr/mdn/guidelines/code_guidelines/html/index.md b/files/fr/mdn/guidelines/code_guidelines/html/index.md new file mode 100644 index 0000000000..086c1f5e34 --- /dev/null +++ b/files/fr/mdn/guidelines/code_guidelines/html/index.md @@ -0,0 +1,162 @@ +--- +title: Lignes directrices pour le HTML +slug: MDN/Guidelines/Code_guidelines/HTML +tags: + - Code + - Guide + - Directives + - HTML + - MDN Meta +translation_of: MDN/Guidelines/Code_guidelines/HTML +--- +
{{MDNSidebar}}
+ +

Les directives suivantes couvrent la manière d'écrire du HTML pour les exemples de code MDN.

+ +

Dans cet article

+ + + +

Doctype et méta-données

+ +
+

Note : Les directives de cette section ne s'appliquent que lorsque vous devez montrer un document HTML complet. La plupart du temps, vous n'aurez pas besoin de le faire ; un extrait est généralement suffisant pour démontrer une fonctionnalité. Lorsque vous utilisez la macro EmbedLiveSample, il suffit d'inclure l'extrait HTML ; il sera automatiquement inséré dans un document HTML complet lors de son affichage.

+
+ +

Doctype

+ +

Vous devez utiliser le doctype HTML5. Il est court, facile à retenir et rétrocompatible :

+ +
<!DOCTYPE html>
+ +

Langue du document

+ +

Définissez la langue du document à l'aide de l'attribut lang de votre élément <html> :

+ +
<html lang="fr">
+ +

C'est bon pour l'accessibilité et les moteurs de recherche, cela aide à localiser le contenu et cela rappelle aux gens d'utiliser les meilleures pratiques.

+ +

Jeu de caractères du document

+ +

Vous devez également définir le jeu de caractères de votre document comme suit :

+ +
<meta charset="utf-8">
+ +

Utilisez UTF-8 à moins que vous n'ayez une très bonne raison de ne pas le faire ; il couvrira vos besoins en caractères à peu près indépendamment de la langue que vous utilisez dans votre document. En outre, vous devriez toujours spécifier le jeu de caractères le plus tôt possible dans le bloc <head> de votre HTML (dans le premier kilooctet), car cela vous protège contre une vulnérabilité de sécurité d'Internet Explorer.

+ +

Méta-balise Viewport

+ +

Enfin, vous devez toujours ajouter la métabalise viewport dans votre HTML <head>, pour donner à l'exemple une meilleure chance de fonctionner sur les appareils mobiles. Vous devez inclure au moins les éléments suivants dans votre document, que vous pourrez modifier ultérieurement en fonction des besoins :

+ +
<meta name="viewport" content="width=device-width">
+ +

Voir Zones d'affichage sur mobiles pour plus de détails.

+ +

Style général de codage des balises

+ +

Utiliser les minuscules

+ +

Utilisez les minuscules pour tous les noms d'éléments et les noms/valeurs d'attributs, car elles sont plus nettes et vous permettent d'écrire plus rapidement les balises :

+ +

C'est bien :

+ +
<p class="nice">Ça a l'air sympa et soigné</p>
+ +

Ce n'est pas très bon :

+ +
<P CLASS="WHOA-THERE">Pourquoi mon balisage crie-t-il ?</P>
+ +

Barre oblique de fermeture (slash)

+ +

N'incluez pas les barres obliques de fin de style XHTML pour les éléments vides, car elles sont inutiles et ralentissent le processus. Elles peuvent également casser les anciens navigateurs si vous ne faites pas attention (bien que, d'après ce dont nous nous souvenons, cela n'a pas été un problème depuis Netscape 4).

+ +

C'est bon :

+ +
<input type="text">
+<hr>
+ +

Les barres obliques ne sont pas nécessaires :

+ +
<input type="text" />
+<hr />
+ +

Guillemets des attributs

+ +

Vous devez mettre toutes les valeurs d'attribut entre guillemets. Il est tentant d'omettre les guillemets puisque HTML5 le permet, mais le balisage est plus net et plus facile à lire si vous les incluez. Par exemple, ceci est mieux :

+ +
<img src="images/logo.jpg" alt="Une icône de globe circulaire" class="no-border">
+ +

que ça :

+ +
<img src=images/logo.jpg alt=Une icône de globe circulaire class=no-border>
+ +

Cela peut également causer des problèmes - dans l'exemple ci-dessus, l'attribut alt sera interprété comme plusieurs attributs, car il n'y a pas de guillemets pour spécifier que "Une icône de globe circulaire" est une valeur d'attribut unique.

+ +

Utiliser les guillemets doubles

+ +

Utilisez des guillemets doubles pour le HTML, et non des guillemets simples :

+ +
<p class="important">Yes</p>
+ +
<p class='important'>Nope</p>
+ +

Attributs booléens

+ +

N'écrivez pas les attributs booléens en entier ; vous pouvez simplement écrire le nom de l'attribut pour le définir. Par exemple, vous pouvez écrire :

+ +
required
+ +

Ceci est parfaitement compréhensible et fonctionne bien ; la version plus longue avec la valeur est acceptée mais n'est pas nécessaire :

+ +
required="required"
+ +

Noms de classes et d'ID

+ +

Utilisez des noms de classe/ID sémantiques et séparez les mots multiples par des traits d'union. N'utilisez pas de camelCase.

+ +

Bon :

+ +
<p class="editorial-summary">Blah blah blah</p>
+ +

Mauvais :

+ +
<p class="bigRedBox">Blah blah blah</p>
+ +

Références des entités

+ +

N'utilisez pas inutilement les références d'entités - utilisez le caractère littéral chaque fois que cela est possible (vous devrez toujours échapper les caractères comme les crochets et les guillemets).

+ +

Par exemple, vous pourriez simplement écrire

+ +
<p>© 2018 Me</p>
+ +

Au lieu de

+ +
<p>&copy; 2018 Me</p>
+ +

Cela ne pose aucun problème tant que vous déclarez un jeu de caractères UTF-8.

+ +

De bons exemples HTML sur MDN

+ +

Vous pouvez trouver de bons extraits HTML, concis et significatifs, en haut des pages de référence HTML - nos exemples interactifs sont généralement rédigés de manière à suivre ces directives, mais sachez qu'ils peuvent différer à certains endroits car ils ont pour la plupart été rédigés avant la nouvelle rédaction des directives.

diff --git a/files/fr/mdn/guidelines/code_guidelines/index.html b/files/fr/mdn/guidelines/code_guidelines/index.html deleted file mode 100644 index ab395b6e62..0000000000 --- a/files/fr/mdn/guidelines/code_guidelines/index.html +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Lignes directrices pour les fragments de code -slug: MDN/Guidelines/Code_guidelines -tags: - - CSS - - Code - - Guide - - HTML - - JavaScript - - MDN Meta - - Shell -translation_of: MDN/Guidelines/Code_guidelines -original_slug: MDN/Guidelines/Code_lignesdirectrices ---- -
{{MDNSidebar}}
- -

Cette série de documents décrit les directives de codage et les meilleures pratiques que nous utilisons pour écrire des démonstrations, des extraits de code, des exemples interactifs, etc. à utiliser sur MDN.

- -

Si vous cherchez des lignes directrices à suivre pour rédiger vos exemples de codes, vous êtes au bon endroit. Le plus grand avantage de respecter ces directives est qu'elles favoriseront la cohérence entre nos échantillons et nos démos sur MDN, ce qui augmente la lisibilité et la compréhension en général.

- -
-

Note : Si vous souhaitez obtenir des conseils sur le style du code tel qu'il apparaît sur un article de MDN, plutôt que sur le contenu du code, consultez notre Guide stylistique.

-
- -

Structure d'article

- -

Cet article contient les meilleures pratiques générales de haut niveau pour la rédaction d'exemples de codes MDN. Ses sous-articles sont les suivants :

- - - -

Bonnes pratiques générales

- -

Cette section fournit rapidement les meilleures pratiques générales pour créer un échantillon de code minimal compréhensible afin de démontrer l'utilisation d'une caractéristique ou d'une fonction spécifique.

- -

Les échantillons de code doivent l'être :

- - - -

Il y a une considération primordiale que vous devez garder à l'esprit : Les lecteurs copieront et colleront l'échantillon de code dans leur propre code, et pourront le mettre en production.

- -

Par conséquent, vous devez vous assurer que l'exemple de code est utilisable et suit les meilleures pratiques généralement acceptées, et ne fait rien qui puisse rendre une application peu sûre, grossièrement inefficace, gonflée ou inaccessible. Si l'exemple de code n'est pas utilisable ou ne vaut pas la peine d'être produit, veillez à inclure un avertissement dans un commentaire de code et dans le texte explicatif — s'il s'agit d'un extrait et non d'un exemple complet, précisez-le clairement. Cela signifie également que vous devez fournir toutes les informations nécessaires à l'exécution de l'exemple, y compris les dépendances et la configuration.

- -

Les échantillons de code doivent être aussi autonomes et faciles à comprendre que possible. L'objectif n'est pas nécessairement de produire un code efficace et intelligent qui impressionne les experts et possède une grande fonctionnalité, mais plutôt de produire des exemples de travail réduits qui peuvent être compris le plus rapidement possible.

- -

Les autres meilleures pratiques générales sont les suivantes :

- - diff --git a/files/fr/mdn/guidelines/code_guidelines/index.md b/files/fr/mdn/guidelines/code_guidelines/index.md new file mode 100644 index 0000000000..ab395b6e62 --- /dev/null +++ b/files/fr/mdn/guidelines/code_guidelines/index.md @@ -0,0 +1,64 @@ +--- +title: Lignes directrices pour les fragments de code +slug: MDN/Guidelines/Code_guidelines +tags: + - CSS + - Code + - Guide + - HTML + - JavaScript + - MDN Meta + - Shell +translation_of: MDN/Guidelines/Code_guidelines +original_slug: MDN/Guidelines/Code_lignesdirectrices +--- +
{{MDNSidebar}}
+ +

Cette série de documents décrit les directives de codage et les meilleures pratiques que nous utilisons pour écrire des démonstrations, des extraits de code, des exemples interactifs, etc. à utiliser sur MDN.

+ +

Si vous cherchez des lignes directrices à suivre pour rédiger vos exemples de codes, vous êtes au bon endroit. Le plus grand avantage de respecter ces directives est qu'elles favoriseront la cohérence entre nos échantillons et nos démos sur MDN, ce qui augmente la lisibilité et la compréhension en général.

+ +
+

Note : Si vous souhaitez obtenir des conseils sur le style du code tel qu'il apparaît sur un article de MDN, plutôt que sur le contenu du code, consultez notre Guide stylistique.

+
+ +

Structure d'article

+ +

Cet article contient les meilleures pratiques générales de haut niveau pour la rédaction d'exemples de codes MDN. Ses sous-articles sont les suivants :

+ + + +

Bonnes pratiques générales

+ +

Cette section fournit rapidement les meilleures pratiques générales pour créer un échantillon de code minimal compréhensible afin de démontrer l'utilisation d'une caractéristique ou d'une fonction spécifique.

+ +

Les échantillons de code doivent l'être :

+ + + +

Il y a une considération primordiale que vous devez garder à l'esprit : Les lecteurs copieront et colleront l'échantillon de code dans leur propre code, et pourront le mettre en production.

+ +

Par conséquent, vous devez vous assurer que l'exemple de code est utilisable et suit les meilleures pratiques généralement acceptées, et ne fait rien qui puisse rendre une application peu sûre, grossièrement inefficace, gonflée ou inaccessible. Si l'exemple de code n'est pas utilisable ou ne vaut pas la peine d'être produit, veillez à inclure un avertissement dans un commentaire de code et dans le texte explicatif — s'il s'agit d'un extrait et non d'un exemple complet, précisez-le clairement. Cela signifie également que vous devez fournir toutes les informations nécessaires à l'exécution de l'exemple, y compris les dépendances et la configuration.

+ +

Les échantillons de code doivent être aussi autonomes et faciles à comprendre que possible. L'objectif n'est pas nécessairement de produire un code efficace et intelligent qui impressionne les experts et possède une grande fonctionnalité, mais plutôt de produire des exemples de travail réduits qui peuvent être compris le plus rapidement possible.

+ +

Les autres meilleures pratiques générales sont les suivantes :

+ + diff --git a/files/fr/mdn/guidelines/code_guidelines/javascript/index.html b/files/fr/mdn/guidelines/code_guidelines/javascript/index.html deleted file mode 100644 index a2178f8491..0000000000 --- a/files/fr/mdn/guidelines/code_guidelines/javascript/index.html +++ /dev/null @@ -1,501 +0,0 @@ ---- -title: Lignes directrices pour JavaScript -slug: MDN/Guidelines/Code_guidelines/JavaScript -tags: - - Code - - Guide - - Directives - - JavaScript - - MDN Meta -translation_of: MDN/Guidelines/Code_guidelines/JavaScript ---- -
{{MDNSidebar}}
- -

Les directives suivantes couvrent la manière d'écrire le JavaScript pour les exemples de code MDN.

- -

Ce qui suit est un ensemble assez simple de directives JavaScript. Nous pourrions aller beaucoup plus en profondeur sur ce sujet, mais nous voulons essentiellement fournir des directives simples pour écrire des exemples concis qui seront compréhensibles par le plus grand nombre de personnes possible, plutôt que des directives détaillées pour écrire des applications web complexes. Si vous voulez quelque chose qui entre dans plus de détails, nous vous recommandons le guide stylistique JavaScript d'AirBnB, qui est généralement compatible avec nos directives.

- -

Dans cet article

- - - -

Directives générales sur le JavaScript

- -

Utiliser une syntaxe étendue

- -

Pour JavaScript, nous utilisons une syntaxe étendue, chaque ligne de JS étant placée sur une nouvelle ligne, l'accolade d'ouverture d'un bloc sur la même ligne que l'instruction associée et l'accolade de fermeture sur une nouvelle ligne. Cela permet d'optimiser la lisibilité et de favoriser la cohérence sur le MDN.

- -

Faites ceci

- -
function myFunc() {
-  console.log('Hello!');
-};
- -

Évitez cela

- -
function myFunc() { console.log('Hello!'); };
- -

Nous avons également quelques règles spécifiques concernant l'espacement à l'intérieur des caractéristiques du langage. Vous devez inclure des espaces entre les opérateurs et les opérandes, les paramètres, etc.

- -

C'est plus lisible

- -
if(dayOfWeek === 7 && weather === 'soleil') {
-  goOnTrip('plage', 'voiture', ['crême glacée', 'pelle et sceau', 'serviette de plage']);
-}
- -

que ceci

- -
if(dayOfWeek===7&&weather==='soleil'){
-  goOnTrip('plage','voiture',['crême glacée','pelle et sceau','serviette de plage']);
-}
- -

En outre, gardez ces spécificités à l'esprit :

- - - -

Commentaires JavaScript

- -

Utilisez des commentaires de style JS pour commenter le code qui n'est pas auto-documenté :

- -
// This is a JavaScript-style comment
- -

Mettez vos commentaires sur des lignes séparées précédant le code auquel ils se réfèrent :

- -
function myFunc() {
-  // Affiche la chaîne de caractères "Bonjour" dans la console JS du navigateur.
-  console.log('Bonjour');
-  // Crée un nouveau paragraphe, le remplit de contenu et l'ajoute au <body>
-  let para = document.createElement('p');
-  para.textContent = 'Mon nouveau paragraphe';
-  document.body.appendChild(para);
-}
- -

Notez également que vous devez laisser un espace entre les barres obliques et le commentaire, dans chaque cas.

- -

Utiliser les fonctions ES6

- -

Pour un usage général*, vous pouvez utiliser les fonctionnalités ES6 courantes (telles que les fonctions fléchées, promesses, let/const, littéraux de gabarits, et le syntaxe de décomposition) dans les exemples MDN. Nous les incluons à de nombreux endroits dans ces directives, car nous pensons que l'industrie du Web a généralement atteint un point où ces fonctionnalités sont suffisamment familières pour être compréhensibles. Et pour ceux qui ne les utilisent pas encore, nous aimerions jouer notre rôle en aidant les gens à développer leurs compétences.

- -

Cependant, nous ne recommandons pas encore l'utilisation générale des nouvelles fonctionnalités ES telles que async/await, les virgules de fin sur les listes d'arguments, etc. Nous préférerions que vous ne les utilisiez pas, sauf si cela est strictement nécessaire, et si vous les utilisez, incluez une explication dans votre exemple pour dire ce qu'ils font, avec un lien vers le matériel de référence approprié.

- -
-

Note : Par "usage général", nous entendons la rédaction d'exemples généraux. Les pages de référence couvrant des fonctionnalités spécifiques de l'ES moderne doivent évidemment utiliser les fonctionnalités qu'elles documentent !

-
- -

Variables

- -

Nommage des variables

- -

Pour les noms de variables, utilisez la casse minuscule au format chameau « lowerCamelCase » et, le cas échéant, des noms concis, lisibles par l'homme et sémantiques.

- -

Écrivez comme suit :

- -
let playerScore = 0;
-
-let speed = distance / time;
- -

Éviter ce genre de chose :

- -
let thisIsaveryLONGVariableThatRecordsPlayerscore345654 = 0;
-
-let s = d/t;
-
- -
-

Note : The only place where it is OK to not use human-readable semantic names is where a very common recognized convention exists, such as using i, j, etc. for loop iterators.

-
- -

Déclaration des variables

- -

Lorsque vous déclarez des variables et des constantes, utilisez les mots-clés let et const, pas var.

- -

Si une variable ne sera pas réaffectée, préférez const :

- -
const myName = 'Chris';
-console.log(myName);
-
- -

Sinon, utilisez let :

- -
let myAge = '40';
-myAge++;
-console.log('Happy birthday!');
-
- -

Cet exemple utilise let là où il devrait préférer const. Il fonctionnera mais devrait être évité dans les exemples de code MDN :

- -
let myName = 'Chris';
-console.log(myName);
-
- -

Cet exemple utilise const pour une variable qui est réaffectée. La réaffectation entraînera une erreur :

- -
const myAge = '40';
-myAge++;
-console.log('Happy birthday!');
-
- -

Cet exemple utilise var, ce qui doit être évité dans les exemples de code MDN, sauf si cela est vraiment nécessaire :

- -
var myAge = '40';
-var myName = 'Chris';
- -

Opérateurs et comparaison

- -

Opérateurs ternaires

- -

Les opérateurs ternaires doivent être placés sur une seule ligne :

- -
let status = (age >= 18) ? 'adult' : 'minor';
- -

Pas emboîtés :

- -
let status = (age >= 18)
-  ? 'adult'
-  : 'minor';
- -

C'est beaucoup plus difficile à lire.

- -

Utiliser l'égalité stricte

- -

Utilisez toujours une égalité et une inégalité strictes.

- -

Comme ceci :

- -
name === 'Chris';
-age !== 25;
- -

N'écrivez pas comme ça :

- -
name == 'Chris';
-age != 25;
- -

Utiliser des raccourcis pour les tests booléens

- -

Utilisez des raccourcis pour les tests booléens - utilisez x et !x, et non x === true et x === false.

- -

Instructions de contrôle

- -

Écrivez des instructions de contrôle comme ceci :

- -
if(iceCream) {
-  alert('Woo hoo!');
-}
- -

Pas comme cela :

- -
if (iceCream){
-  alert('Woo hoo!');
-}
- -

N'oubliez pas non plus :

- - - -

Chaînes de caractères

- -

Utiliser des modèles littéraux

- -

Pour insérer des valeurs dans des chaînes de caractères, utilisez des chaînes de caractères littérales.

- -

Comme suit :

- -
let myName = 'Chris';
-console.log(`Hi! I'm ${myName}!`);
- -

En évitant d'écrire :

- -
let myName = 'Chris';
-console.log('Hi! I\'m' + myName + '!');
- -

Utiliser textContent, et non innerHTML

- -

Lorsque vous insérez des chaînes de caractères dans les nœuds du DOM, utilisez la fonction Node.textContent:

- -
let text = 'Bonjour à vous tous, braves gens';
-const para = document.createElement('p');
-para.textContent = text;
- -

Et pas Element.innerHTML:

- -
let text = 'Bonjour à vous tous, braves gens';
-const para = document.createElement('p');
-para.innerHTML = text;
- -

Le textContent est beaucoup plus efficace, et moins sujet aux erreurs que le innerHTML.

- -

Conditions

- -

Usage général des boucles

- -

When loops are required, feel free to choose an appropriate loop out of the available ones (for, for...of, while, etc.) Just make sure to keep the code as understandable as possible.

- -

Lorsque vous utilisez des boucles for/for...of, veillez à définir correctement l'initialisateur, avec un mot clé let :

- -
let cats = ['Athena', 'Luna'];
-for(let i of cats) {
-  console.log(i);
-}
-
- -

Pas

- -
let cats = ['Athena', 'Luna'];
-for(i of cats) {
-  console.log(i);
-}
-
- -

Gardez également à l'esprit :

- - - -

Les instructions switch

- -

Formatez les instructions switch comme suit :

- -
let expr = 'Papayes';
-switch(expr) {
-  case 'Oranges':
-    console.log('Les oranges sont à 1,10 € le kilo.');
-    break;
-  case 'Papayes':
-    console.log('Les mangues et les papayes sont à 5,24 € le kilo.');
-    // résultat attendu : "Les mangues et les papayes sont à 5,24 € le kilo."
-    break;
-  default:
-    console.log('Désolé, nous n'avons plus de ' + expr + '.');
-}
- -

Fonctions et objets

- -

Nommage des fonctions

- -

Pour les noms de fonctions, utilisez la casse minuscule au format chameau « lowevCamelCase » et, le cas échéant, des noms concis, lisibles par l'homme et sémantiques.

- -

Par exemple :

- -
function sayHello() {
-  alert('Bonjour !');
-};
- -

En évitant de faire :

- -
function SayHello() {
-  alert('Bonjour !');
-};
-
-function notVeryObviousName() {
-  alert('Bonjour !');
-};
-
- -
-

Note : Le seul endroit où il est acceptable de ne pas utiliser des noms sémantiques lisibles par l'homme est lorsqu'une convention reconnue très courante existe, comme l'utilisation de i, j, etc. pour les itérateurs de boucle.

-
- -

Définition des fonctions

- -

Dans la mesure du possible, utilisez la déclaration fonction pour définir des fonctions sur des expressions de fonction :

- -

Faites comme ça :

- -
function sum(a, b) {
-  return a + b;
-}
- -

Pas comme ça :

- -
let sum = function(a, b) {
-  return a + b;
-}
- -

Lorsque vous utilisez des fonctions anonymes à l'intérieur d'une méthode qui requiert une fonction comme paramètre, il est acceptable (mais pas obligatoire) d'utiliser une fonction flèche pour rendre le code plus court et plus propre.

- -

Donc, au lieu de ça :

- -
const array1 = [1, 2, 3, 4];
-let sum = array.reduce(function(a, b) {
-  return a + b;
-});
- -

vous pourriez écrire ceci :

- -
const array = [1, 2, 3, 4];
-let sum = array.reduce((a, b) =>
-  a + b
-);
- -

N'oubliez pas non plus :

- - - -

Création d'objets

- -

Utilisez des littéraux - et non des constructeurs - pour créer des objets généraux (c'est-à-dire lorsque les classes ne sont pas concernées) :

- -

Par exemple :

- -
let myObject = { };
- -

Et pas :

- -
let myObject = new Object();
- -

Classes d'objets

- -

Utilisez la syntaxe de classe ES pour les objets, et non les constructeurs à l'ancienne.

- -

À titre d'exemples :

- -
class Person {
-  constructor(name, age, gender) {
-    this.name = name;
-    this.age = age;
-    this.gender = gender;
-  }
-
-  greeting() {
-    console.log(`Salut ! Je m'appelle ${this.name}`);
-  };
-}
- -

Utilisez extends pour l'héritage :

- -
class Teacher extends Person {
-  ...
-}
- -

Nommage des objets

- -

Lorsque vous définissez une classe d'objets (comme ci-dessus), utilisez l'écriture de casse au format chameau en majuscule « UpperCamelCase » (également connue sous le nom de « PascalCasing ») pour le nom de la classe, et la casse en minuscule « lowerCamelCase » pour les noms des propriétés et des méthodes de l'objet.

- -

Lors de la définition d'une instance d'objet, qu'il s'agisse d'un littéral ou d'un constructeur, utilisez le lowerCamelCase pour le nom de l'instance :

- -
let hanSolo = new Person('Han Solo', 25, 'male');
-
-let hanSolo = {
-  name: 'Han Solo',
-  age: 25,
-  gender: 'male'
-}
- -

Tableaux

- -

Création de tableaux

- -

Utilisez des littéraux - et non des constructeurs - pour créer des tableaux :

- -

Comme ceci :

- -
let myArray = [ ];
- -

Pas comme ça :

- -
let myArray = new Array(length);
- -

Ajout à un tableau

- -

Pour ajouter des éléments à un tableau, utilisez push(), et non l'affectation directe. Étant donné le tableau suivant :

- -
const pets = [];
- -

faites ça :

- -
pets.push('cat');
- -

et pas ça :

- -
pets[pets.length] = 'cat';
- -

Traitement des erreurs

- -

Si certains états de votre programme lancent des erreurs non attrapées, ils interrompent l'exécution et réduisent potentiellement l'utilité de l'exemple. Vous devriez donc attraper les erreurs en utilisant un bloc try...catch :

- -
try {
-  console.log(results);
-}
-catch(e) {
-  console.error(e);
-}
- -

De bons exemples de JavaScript sur MDN

- -

Vous pouvez trouver de bons extraits de JavaScript, concis et significatifs, en haut de nos pages Référence du langage JavaScript - parcourez-les pour en trouver.

- -

Nos exemples interactifs (et autres) sont généralement rédigés de manière à suivre les directives ci-dessus, mais sachez qu'ils peuvent différer à certains endroits, car ils ont été rédigés pour la plupart avant que les directives ne soient nouvellement rédigées.

- -

En ce qui concerne les exemples d'API, nous aimerions mettre en avant quelques exemples qui nous semblent bons :

- - diff --git a/files/fr/mdn/guidelines/code_guidelines/javascript/index.md b/files/fr/mdn/guidelines/code_guidelines/javascript/index.md new file mode 100644 index 0000000000..a2178f8491 --- /dev/null +++ b/files/fr/mdn/guidelines/code_guidelines/javascript/index.md @@ -0,0 +1,501 @@ +--- +title: Lignes directrices pour JavaScript +slug: MDN/Guidelines/Code_guidelines/JavaScript +tags: + - Code + - Guide + - Directives + - JavaScript + - MDN Meta +translation_of: MDN/Guidelines/Code_guidelines/JavaScript +--- +
{{MDNSidebar}}
+ +

Les directives suivantes couvrent la manière d'écrire le JavaScript pour les exemples de code MDN.

+ +

Ce qui suit est un ensemble assez simple de directives JavaScript. Nous pourrions aller beaucoup plus en profondeur sur ce sujet, mais nous voulons essentiellement fournir des directives simples pour écrire des exemples concis qui seront compréhensibles par le plus grand nombre de personnes possible, plutôt que des directives détaillées pour écrire des applications web complexes. Si vous voulez quelque chose qui entre dans plus de détails, nous vous recommandons le guide stylistique JavaScript d'AirBnB, qui est généralement compatible avec nos directives.

+ +

Dans cet article

+ + + +

Directives générales sur le JavaScript

+ +

Utiliser une syntaxe étendue

+ +

Pour JavaScript, nous utilisons une syntaxe étendue, chaque ligne de JS étant placée sur une nouvelle ligne, l'accolade d'ouverture d'un bloc sur la même ligne que l'instruction associée et l'accolade de fermeture sur une nouvelle ligne. Cela permet d'optimiser la lisibilité et de favoriser la cohérence sur le MDN.

+ +

Faites ceci

+ +
function myFunc() {
+  console.log('Hello!');
+};
+ +

Évitez cela

+ +
function myFunc() { console.log('Hello!'); };
+ +

Nous avons également quelques règles spécifiques concernant l'espacement à l'intérieur des caractéristiques du langage. Vous devez inclure des espaces entre les opérateurs et les opérandes, les paramètres, etc.

+ +

C'est plus lisible

+ +
if(dayOfWeek === 7 && weather === 'soleil') {
+  goOnTrip('plage', 'voiture', ['crême glacée', 'pelle et sceau', 'serviette de plage']);
+}
+ +

que ceci

+ +
if(dayOfWeek===7&&weather==='soleil'){
+  goOnTrip('plage','voiture',['crême glacée','pelle et sceau','serviette de plage']);
+}
+ +

En outre, gardez ces spécificités à l'esprit :

+ + + +

Commentaires JavaScript

+ +

Utilisez des commentaires de style JS pour commenter le code qui n'est pas auto-documenté :

+ +
// This is a JavaScript-style comment
+ +

Mettez vos commentaires sur des lignes séparées précédant le code auquel ils se réfèrent :

+ +
function myFunc() {
+  // Affiche la chaîne de caractères "Bonjour" dans la console JS du navigateur.
+  console.log('Bonjour');
+  // Crée un nouveau paragraphe, le remplit de contenu et l'ajoute au <body>
+  let para = document.createElement('p');
+  para.textContent = 'Mon nouveau paragraphe';
+  document.body.appendChild(para);
+}
+ +

Notez également que vous devez laisser un espace entre les barres obliques et le commentaire, dans chaque cas.

+ +

Utiliser les fonctions ES6

+ +

Pour un usage général*, vous pouvez utiliser les fonctionnalités ES6 courantes (telles que les fonctions fléchées, promesses, let/const, littéraux de gabarits, et le syntaxe de décomposition) dans les exemples MDN. Nous les incluons à de nombreux endroits dans ces directives, car nous pensons que l'industrie du Web a généralement atteint un point où ces fonctionnalités sont suffisamment familières pour être compréhensibles. Et pour ceux qui ne les utilisent pas encore, nous aimerions jouer notre rôle en aidant les gens à développer leurs compétences.

+ +

Cependant, nous ne recommandons pas encore l'utilisation générale des nouvelles fonctionnalités ES telles que async/await, les virgules de fin sur les listes d'arguments, etc. Nous préférerions que vous ne les utilisiez pas, sauf si cela est strictement nécessaire, et si vous les utilisez, incluez une explication dans votre exemple pour dire ce qu'ils font, avec un lien vers le matériel de référence approprié.

+ +
+

Note : Par "usage général", nous entendons la rédaction d'exemples généraux. Les pages de référence couvrant des fonctionnalités spécifiques de l'ES moderne doivent évidemment utiliser les fonctionnalités qu'elles documentent !

+
+ +

Variables

+ +

Nommage des variables

+ +

Pour les noms de variables, utilisez la casse minuscule au format chameau « lowerCamelCase » et, le cas échéant, des noms concis, lisibles par l'homme et sémantiques.

+ +

Écrivez comme suit :

+ +
let playerScore = 0;
+
+let speed = distance / time;
+ +

Éviter ce genre de chose :

+ +
let thisIsaveryLONGVariableThatRecordsPlayerscore345654 = 0;
+
+let s = d/t;
+
+ +
+

Note : The only place where it is OK to not use human-readable semantic names is where a very common recognized convention exists, such as using i, j, etc. for loop iterators.

+
+ +

Déclaration des variables

+ +

Lorsque vous déclarez des variables et des constantes, utilisez les mots-clés let et const, pas var.

+ +

Si une variable ne sera pas réaffectée, préférez const :

+ +
const myName = 'Chris';
+console.log(myName);
+
+ +

Sinon, utilisez let :

+ +
let myAge = '40';
+myAge++;
+console.log('Happy birthday!');
+
+ +

Cet exemple utilise let là où il devrait préférer const. Il fonctionnera mais devrait être évité dans les exemples de code MDN :

+ +
let myName = 'Chris';
+console.log(myName);
+
+ +

Cet exemple utilise const pour une variable qui est réaffectée. La réaffectation entraînera une erreur :

+ +
const myAge = '40';
+myAge++;
+console.log('Happy birthday!');
+
+ +

Cet exemple utilise var, ce qui doit être évité dans les exemples de code MDN, sauf si cela est vraiment nécessaire :

+ +
var myAge = '40';
+var myName = 'Chris';
+ +

Opérateurs et comparaison

+ +

Opérateurs ternaires

+ +

Les opérateurs ternaires doivent être placés sur une seule ligne :

+ +
let status = (age >= 18) ? 'adult' : 'minor';
+ +

Pas emboîtés :

+ +
let status = (age >= 18)
+  ? 'adult'
+  : 'minor';
+ +

C'est beaucoup plus difficile à lire.

+ +

Utiliser l'égalité stricte

+ +

Utilisez toujours une égalité et une inégalité strictes.

+ +

Comme ceci :

+ +
name === 'Chris';
+age !== 25;
+ +

N'écrivez pas comme ça :

+ +
name == 'Chris';
+age != 25;
+ +

Utiliser des raccourcis pour les tests booléens

+ +

Utilisez des raccourcis pour les tests booléens - utilisez x et !x, et non x === true et x === false.

+ +

Instructions de contrôle

+ +

Écrivez des instructions de contrôle comme ceci :

+ +
if(iceCream) {
+  alert('Woo hoo!');
+}
+ +

Pas comme cela :

+ +
if (iceCream){
+  alert('Woo hoo!');
+}
+ +

N'oubliez pas non plus :

+ + + +

Chaînes de caractères

+ +

Utiliser des modèles littéraux

+ +

Pour insérer des valeurs dans des chaînes de caractères, utilisez des chaînes de caractères littérales.

+ +

Comme suit :

+ +
let myName = 'Chris';
+console.log(`Hi! I'm ${myName}!`);
+ +

En évitant d'écrire :

+ +
let myName = 'Chris';
+console.log('Hi! I\'m' + myName + '!');
+ +

Utiliser textContent, et non innerHTML

+ +

Lorsque vous insérez des chaînes de caractères dans les nœuds du DOM, utilisez la fonction Node.textContent:

+ +
let text = 'Bonjour à vous tous, braves gens';
+const para = document.createElement('p');
+para.textContent = text;
+ +

Et pas Element.innerHTML:

+ +
let text = 'Bonjour à vous tous, braves gens';
+const para = document.createElement('p');
+para.innerHTML = text;
+ +

Le textContent est beaucoup plus efficace, et moins sujet aux erreurs que le innerHTML.

+ +

Conditions

+ +

Usage général des boucles

+ +

When loops are required, feel free to choose an appropriate loop out of the available ones (for, for...of, while, etc.) Just make sure to keep the code as understandable as possible.

+ +

Lorsque vous utilisez des boucles for/for...of, veillez à définir correctement l'initialisateur, avec un mot clé let :

+ +
let cats = ['Athena', 'Luna'];
+for(let i of cats) {
+  console.log(i);
+}
+
+ +

Pas

+ +
let cats = ['Athena', 'Luna'];
+for(i of cats) {
+  console.log(i);
+}
+
+ +

Gardez également à l'esprit :

+ + + +

Les instructions switch

+ +

Formatez les instructions switch comme suit :

+ +
let expr = 'Papayes';
+switch(expr) {
+  case 'Oranges':
+    console.log('Les oranges sont à 1,10 € le kilo.');
+    break;
+  case 'Papayes':
+    console.log('Les mangues et les papayes sont à 5,24 € le kilo.');
+    // résultat attendu : "Les mangues et les papayes sont à 5,24 € le kilo."
+    break;
+  default:
+    console.log('Désolé, nous n'avons plus de ' + expr + '.');
+}
+ +

Fonctions et objets

+ +

Nommage des fonctions

+ +

Pour les noms de fonctions, utilisez la casse minuscule au format chameau « lowevCamelCase » et, le cas échéant, des noms concis, lisibles par l'homme et sémantiques.

+ +

Par exemple :

+ +
function sayHello() {
+  alert('Bonjour !');
+};
+ +

En évitant de faire :

+ +
function SayHello() {
+  alert('Bonjour !');
+};
+
+function notVeryObviousName() {
+  alert('Bonjour !');
+};
+
+ +
+

Note : Le seul endroit où il est acceptable de ne pas utiliser des noms sémantiques lisibles par l'homme est lorsqu'une convention reconnue très courante existe, comme l'utilisation de i, j, etc. pour les itérateurs de boucle.

+
+ +

Définition des fonctions

+ +

Dans la mesure du possible, utilisez la déclaration fonction pour définir des fonctions sur des expressions de fonction :

+ +

Faites comme ça :

+ +
function sum(a, b) {
+  return a + b;
+}
+ +

Pas comme ça :

+ +
let sum = function(a, b) {
+  return a + b;
+}
+ +

Lorsque vous utilisez des fonctions anonymes à l'intérieur d'une méthode qui requiert une fonction comme paramètre, il est acceptable (mais pas obligatoire) d'utiliser une fonction flèche pour rendre le code plus court et plus propre.

+ +

Donc, au lieu de ça :

+ +
const array1 = [1, 2, 3, 4];
+let sum = array.reduce(function(a, b) {
+  return a + b;
+});
+ +

vous pourriez écrire ceci :

+ +
const array = [1, 2, 3, 4];
+let sum = array.reduce((a, b) =>
+  a + b
+);
+ +

N'oubliez pas non plus :

+ + + +

Création d'objets

+ +

Utilisez des littéraux - et non des constructeurs - pour créer des objets généraux (c'est-à-dire lorsque les classes ne sont pas concernées) :

+ +

Par exemple :

+ +
let myObject = { };
+ +

Et pas :

+ +
let myObject = new Object();
+ +

Classes d'objets

+ +

Utilisez la syntaxe de classe ES pour les objets, et non les constructeurs à l'ancienne.

+ +

À titre d'exemples :

+ +
class Person {
+  constructor(name, age, gender) {
+    this.name = name;
+    this.age = age;
+    this.gender = gender;
+  }
+
+  greeting() {
+    console.log(`Salut ! Je m'appelle ${this.name}`);
+  };
+}
+ +

Utilisez extends pour l'héritage :

+ +
class Teacher extends Person {
+  ...
+}
+ +

Nommage des objets

+ +

Lorsque vous définissez une classe d'objets (comme ci-dessus), utilisez l'écriture de casse au format chameau en majuscule « UpperCamelCase » (également connue sous le nom de « PascalCasing ») pour le nom de la classe, et la casse en minuscule « lowerCamelCase » pour les noms des propriétés et des méthodes de l'objet.

+ +

Lors de la définition d'une instance d'objet, qu'il s'agisse d'un littéral ou d'un constructeur, utilisez le lowerCamelCase pour le nom de l'instance :

+ +
let hanSolo = new Person('Han Solo', 25, 'male');
+
+let hanSolo = {
+  name: 'Han Solo',
+  age: 25,
+  gender: 'male'
+}
+ +

Tableaux

+ +

Création de tableaux

+ +

Utilisez des littéraux - et non des constructeurs - pour créer des tableaux :

+ +

Comme ceci :

+ +
let myArray = [ ];
+ +

Pas comme ça :

+ +
let myArray = new Array(length);
+ +

Ajout à un tableau

+ +

Pour ajouter des éléments à un tableau, utilisez push(), et non l'affectation directe. Étant donné le tableau suivant :

+ +
const pets = [];
+ +

faites ça :

+ +
pets.push('cat');
+ +

et pas ça :

+ +
pets[pets.length] = 'cat';
+ +

Traitement des erreurs

+ +

Si certains états de votre programme lancent des erreurs non attrapées, ils interrompent l'exécution et réduisent potentiellement l'utilité de l'exemple. Vous devriez donc attraper les erreurs en utilisant un bloc try...catch :

+ +
try {
+  console.log(results);
+}
+catch(e) {
+  console.error(e);
+}
+ +

De bons exemples de JavaScript sur MDN

+ +

Vous pouvez trouver de bons extraits de JavaScript, concis et significatifs, en haut de nos pages Référence du langage JavaScript - parcourez-les pour en trouver.

+ +

Nos exemples interactifs (et autres) sont généralement rédigés de manière à suivre les directives ci-dessus, mais sachez qu'ils peuvent différer à certains endroits, car ils ont été rédigés pour la plupart avant que les directives ne soient nouvellement rédigées.

+ +

En ce qui concerne les exemples d'API, nous aimerions mettre en avant quelques exemples qui nous semblent bons :

+ + diff --git a/files/fr/mdn/guidelines/code_guidelines/shell/index.html b/files/fr/mdn/guidelines/code_guidelines/shell/index.html deleted file mode 100644 index a3a1cba4b0..0000000000 --- a/files/fr/mdn/guidelines/code_guidelines/shell/index.html +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Lignes directrices des exemples de lignes de commande -slug: MDN/Guidelines/Code_guidelines/Shell -tags: - - Code - - Guide - - Guidelines - - MDN Meta - - Shell -translation_of: MDN/Guidelines/Code_guidelines/Shell ---- -
{{MDNSidebar}}
- -

Les directives suivantes expliquent comment rédiger des exemples de lignes de commande sur MDN.

- -

Les commandes Shell en bref

- -

Un shell est un programme qui attend que vous tapiez une commande et que vous appuyiez sur la touche retour. Pour indiquer les commandes que vous devez taper, la documentation MDN les répertorie dans un bloc de code, similaire aux exemples de code. Un tel bloc ressemble à ceci :

- -
# Cela peut prendre un certain temps…
-hg clone https://hg.mozilla.org/mozilla-central/ firefox
-cd firefox
- -

Directives

- -

Il existe quelques directives à suivre lors de l'écriture d'un bloc de code shell :

- - - -

De bons exemples de commandes shell sur le MDN

- -

Nos Documents de développement côté serveur de Django montrent une bonne pratique de présentation des commandes de l'invite shell, etc. sur le MDN. Regardez Configurer un environnement de développement Django par exemple.

- diff --git a/files/fr/mdn/guidelines/code_guidelines/shell/index.md b/files/fr/mdn/guidelines/code_guidelines/shell/index.md new file mode 100644 index 0000000000..a3a1cba4b0 --- /dev/null +++ b/files/fr/mdn/guidelines/code_guidelines/shell/index.md @@ -0,0 +1,37 @@ +--- +title: Lignes directrices des exemples de lignes de commande +slug: MDN/Guidelines/Code_guidelines/Shell +tags: + - Code + - Guide + - Guidelines + - MDN Meta + - Shell +translation_of: MDN/Guidelines/Code_guidelines/Shell +--- +
{{MDNSidebar}}
+ +

Les directives suivantes expliquent comment rédiger des exemples de lignes de commande sur MDN.

+ +

Les commandes Shell en bref

+ +

Un shell est un programme qui attend que vous tapiez une commande et que vous appuyiez sur la touche retour. Pour indiquer les commandes que vous devez taper, la documentation MDN les répertorie dans un bloc de code, similaire aux exemples de code. Un tel bloc ressemble à ceci :

+ +
# Cela peut prendre un certain temps…
+hg clone https://hg.mozilla.org/mozilla-central/ firefox
+cd firefox
+ +

Directives

+ +

Il existe quelques directives à suivre lors de l'écriture d'un bloc de code shell :

+ + + +

De bons exemples de commandes shell sur le MDN

+ +

Nos Documents de développement côté serveur de Django montrent une bonne pratique de présentation des commandes de l'invite shell, etc. sur le MDN. Regardez Configurer un environnement de développement Django par exemple.

+ diff --git a/files/fr/mdn/guidelines/conventions_definitions/index.html b/files/fr/mdn/guidelines/conventions_definitions/index.html deleted file mode 100644 index 72ac92bc7c..0000000000 --- a/files/fr/mdn/guidelines/conventions_definitions/index.html +++ /dev/null @@ -1,175 +0,0 @@ ---- -title: Conventions et définitions relatives à MDN -slug: MDN/Guidelines/Conventions_definitions -tags: - - Documentation - - Guide - - Guidelines - - MDN - - MDN Meta -translation_of: MDN/Guidelines/Conventions_definitions ---- -
{{MDNSidebar}}
- -

Cet article définit certaines conventions et définitions couramment utilisées sur MDN et qui pourraient ne pas être évidentes au sein de la documentation.

- -

Définitions

- -

Déprécié et obsolète

- -

Les adjectifs déprécié et obsolète sont souvent associés à des technologies ou à des spécifications : qu'est-ce que cela signifie ?

- -
-
Déprécié (deprecated en anglais)
-
Sur MDN, le terme déprécié est utilisé afin d'indiquer qu'une API ou une technologie n'est plus recommandée bien qu'elle soit toujours implémentée et qu'elle puisse encore fonctionner. Nous avons mis à jour la définition utilisée pour le projet browser-compat-data qui indique "cette fonctionnalité n'est désormais plus recommandée. Elle pourra être supprimée à l'avenir ou être conservée uniquement à des fins de compatibilité. Veuillez éviter d'utiliser cette fonctionnalité."
-
Obsolète
-
Sur MDN, le terme obsolète est utilisé afin d'indiquer une API ou une technologie qui n'est plus recommandée et qui n'est plus implémentée dans les navigateurs. Cette nuance avec la dépréciation pouvait être source de confusion et peu utile (dans les deux cas, on doit éviter d'utiliser une telle fonctionnalité pour un site ou une application en production). Nous n'utilisons plus cette notion désormais et toute occurrence devrait être retirée/remplacée par « déprécié ».
-
- -

Expérimental

- -

Expérimental peut avoir différentes significations en fonction du contexte. Lorsqu'on décrit une technologie comme expérimentale sur MDN, cela signifie qu'elle est en cours de conception/implémentation et en train d'être ajoutée à la plateforme web (ou que son ajout est envisagé).

- -

Au moins un des deux points qui suivent sera vérifié :

- - - -

Si l'une ou l'autre (ou les deux) de ces propositions est vraie, il est préférable de réfléchir avant d'ajouter cette technologique à un projet de production (qui n'est ni une démonstration ni une expérimentation). Voir aussi la définition d'« expérimental » dans le projet browser-compat-data.

- -

À l'inverse, quelque chose n'est plus expérimental lorsque :

- - - -

Le ou a toute son importance ici. Généralement, si une technologie est implémentée sur différents navigateurs principaux, la spécification sera stable. Toutefois, ce n'est pas toujours le cas. On a aussi des technologies dont la spécification est stable mais qui ne sont pas implémentées nativement dans les navigateurs (voir IMSC, par exemple).

- -

Pages archivées

- -

Les pages archivées sont des pages stockées dans les archives MDN pour le contenu obsolète. Ces pages contiennent des informations caduques qui ne sont plus directement utiles.

- -

Pour la plupart, elles concernent des projets Mozilla qui ont été arrêtés et qu'on ne devrait plus utiliser. Elles ne sont cependant pas supprimées en raison de leur valeur historique et de certains concepts ou idées qui pourraient s'avérer utiles pour de futurs projets (un bon exemple est le projet B2G (Firefox OS)).

- -

Comment décider de l'archivage d'une page ?

- -

Une page devrait être archivée si elle s'inscrit dans la description précédente. Pour archiver une page, voir la documentation correspondante sur GitHub.

- -

Pages supprimées

- -

Les pages supprimées ont été explicitement supprimées de MDN. On aura par exemple l'interface SharedKeyframeList et le constructeur SharedKeyframeList(). Ces pages contenaient des informations qui ne sont plus utiles à qui que ce soit et/ou qui sont incorrectes au point qu'elles peuvent être source de confusion ou d'interprétations erronées.

- -

Il peut s'agir :

- - - -

Comment décider de la suppression d'une page ?

- -

Une page devrait être supprimée si elle correspond à la description précédente. Pour supprimer une page, voir la documentation sur GitHub.

- -

Quand documenter de nouvelles technologies

- -

Sur MDN, nous cherchons continuellement à documenter les technologies web standard comme il se doit. Il faut donc trouver un équilibre entre une documentation publiée suffisamment tôt afin que les développeurs puissent découvrir les nouvelles fonctionnalités lorsqu'ils en ont besoin et une documentation publiée suffisamment tard afin que la technologie en question soit suffisamment mature et stable afin que la documentation n'ait pas à être réécrite constamment ou à être supprimée rapidement suite à des changements de rupture dans les spécifications.

- -

En général, le seuil pour déclencher la documentation d'une nouvelle technologie web correspond au moment où :

- -

« La fonctionnalité est en voie de standardisation et implémentée quelque part. »

- -

Une nouvelle technologie mérite sans doute d'être documentée si :

- - - -

Il faut prendre ses précautions quant à la documentation d'une nouvelle technologie si :

- - - -

Une nouvelle technologie ne doit pas être documentée si :

- - - -

Conventions

- -

Lors du retrait d'une fonctionnalité de la spécification

- -

Il arrive parfois, pendant le développement d'une spécification et au fur à et mesure de l'évolution de standards évolutifs que de nouveaux éléments, de nouvelles méthodes ou propriétés ou autres soient ajoutés à la spécification, y restent pendant quelque temps avant d'être retirés. Cela arrive parfois rapidement et peut aussi prendre plusieurs mois ou années avant que la suppression soit effectuée. Gérer cette suppression dans la documentation peut alors s'avérer délicat. Voici quelques lignes directrices pour vous aider à décider de ce qu'il faut faire.

- -
-

Note : Pour la suite de cette discussion, le terme « élément » sera utilisé de façon générique pour indique n'importe quel objet qui peut faire partie d'une spécification : un élément, un attribut d'un élément, une interface, une méthode spécifique, une propriété, un membre d'une interface, etc.

-
- - - -

Les formulations exactes des avertissements et autres messages doivent être adaptées si besoin. En cas de doute sur la formulation, n'hésitez pas à vous rendre sur le canal MDN sur Matrix ou sur le forum de discussion Discourse.

- -

Copier du contenu d'une source tierce sur MDN

- -

Il existe souvent du contenu utile sur un sujet donné en dehors de MDN. Toutefois, copier ce contenu peut s'accompagner de pénalités légales ou techniques.

- -

Sur le plan technique, les moteurs de recherche ont tendance à pénaliser le classement d'un site qui reproduit du contenu existant par ailleurs. Il est donc préférable d'avoir du contenu original sur MDN pour veiller au bon référencement. On peut tout à fait ajouter des liens vers du contenu externe.

- -

Sur le plan légal, il faut être autorisé à contribuer au contenu et il doit être sous une licence et une attribution compatible avec celle de MDN.

- - - -

Comment indiquer un conflit de spécification

- -

Il arrive (rarement) qu'il y ait un conflit entre les différentes versions d'une spécification (généralement pour celles du W3C et du WHATWG). Par exemple, une des spécifications peut indiquer une fonctionnalité comme dépréciée tandis que l'autre n'indique pas cet état. Dans ces cas, on étudiera le comportement réel des navigateurs et on écrira une note afin d'indiquer cet état. Ainsi, en janvier 2019, l'attribut global inputmode était touché par un conflit de spécification qui était indiqué ainsi sur la page :

- -
-

Attention : Conflit de spécification : La spécification WHATWG liste l'attribut inputmode et les navigateurs travaillent à son implémentation. La spécification W3C HTML 5.2 ne le mentionne plus en revanche (ce qui indique qu'il est considéré comme obsolète). Jusqu'à ce qu'un consensus soit atteint, on pourra considérer que c'est la définition du WHATWG qui est correcte.

-
diff --git a/files/fr/mdn/guidelines/conventions_definitions/index.md b/files/fr/mdn/guidelines/conventions_definitions/index.md new file mode 100644 index 0000000000..72ac92bc7c --- /dev/null +++ b/files/fr/mdn/guidelines/conventions_definitions/index.md @@ -0,0 +1,175 @@ +--- +title: Conventions et définitions relatives à MDN +slug: MDN/Guidelines/Conventions_definitions +tags: + - Documentation + - Guide + - Guidelines + - MDN + - MDN Meta +translation_of: MDN/Guidelines/Conventions_definitions +--- +
{{MDNSidebar}}
+ +

Cet article définit certaines conventions et définitions couramment utilisées sur MDN et qui pourraient ne pas être évidentes au sein de la documentation.

+ +

Définitions

+ +

Déprécié et obsolète

+ +

Les adjectifs déprécié et obsolète sont souvent associés à des technologies ou à des spécifications : qu'est-ce que cela signifie ?

+ +
+
Déprécié (deprecated en anglais)
+
Sur MDN, le terme déprécié est utilisé afin d'indiquer qu'une API ou une technologie n'est plus recommandée bien qu'elle soit toujours implémentée et qu'elle puisse encore fonctionner. Nous avons mis à jour la définition utilisée pour le projet browser-compat-data qui indique "cette fonctionnalité n'est désormais plus recommandée. Elle pourra être supprimée à l'avenir ou être conservée uniquement à des fins de compatibilité. Veuillez éviter d'utiliser cette fonctionnalité."
+
Obsolète
+
Sur MDN, le terme obsolète est utilisé afin d'indiquer une API ou une technologie qui n'est plus recommandée et qui n'est plus implémentée dans les navigateurs. Cette nuance avec la dépréciation pouvait être source de confusion et peu utile (dans les deux cas, on doit éviter d'utiliser une telle fonctionnalité pour un site ou une application en production). Nous n'utilisons plus cette notion désormais et toute occurrence devrait être retirée/remplacée par « déprécié ».
+
+ +

Expérimental

+ +

Expérimental peut avoir différentes significations en fonction du contexte. Lorsqu'on décrit une technologie comme expérimentale sur MDN, cela signifie qu'elle est en cours de conception/implémentation et en train d'être ajoutée à la plateforme web (ou que son ajout est envisagé).

+ +

Au moins un des deux points qui suivent sera vérifié :

+ + + +

Si l'une ou l'autre (ou les deux) de ces propositions est vraie, il est préférable de réfléchir avant d'ajouter cette technologique à un projet de production (qui n'est ni une démonstration ni une expérimentation). Voir aussi la définition d'« expérimental » dans le projet browser-compat-data.

+ +

À l'inverse, quelque chose n'est plus expérimental lorsque :

+ + + +

Le ou a toute son importance ici. Généralement, si une technologie est implémentée sur différents navigateurs principaux, la spécification sera stable. Toutefois, ce n'est pas toujours le cas. On a aussi des technologies dont la spécification est stable mais qui ne sont pas implémentées nativement dans les navigateurs (voir IMSC, par exemple).

+ +

Pages archivées

+ +

Les pages archivées sont des pages stockées dans les archives MDN pour le contenu obsolète. Ces pages contiennent des informations caduques qui ne sont plus directement utiles.

+ +

Pour la plupart, elles concernent des projets Mozilla qui ont été arrêtés et qu'on ne devrait plus utiliser. Elles ne sont cependant pas supprimées en raison de leur valeur historique et de certains concepts ou idées qui pourraient s'avérer utiles pour de futurs projets (un bon exemple est le projet B2G (Firefox OS)).

+ +

Comment décider de l'archivage d'une page ?

+ +

Une page devrait être archivée si elle s'inscrit dans la description précédente. Pour archiver une page, voir la documentation correspondante sur GitHub.

+ +

Pages supprimées

+ +

Les pages supprimées ont été explicitement supprimées de MDN. On aura par exemple l'interface SharedKeyframeList et le constructeur SharedKeyframeList(). Ces pages contenaient des informations qui ne sont plus utiles à qui que ce soit et/ou qui sont incorrectes au point qu'elles peuvent être source de confusion ou d'interprétations erronées.

+ +

Il peut s'agir :

+ + + +

Comment décider de la suppression d'une page ?

+ +

Une page devrait être supprimée si elle correspond à la description précédente. Pour supprimer une page, voir la documentation sur GitHub.

+ +

Quand documenter de nouvelles technologies

+ +

Sur MDN, nous cherchons continuellement à documenter les technologies web standard comme il se doit. Il faut donc trouver un équilibre entre une documentation publiée suffisamment tôt afin que les développeurs puissent découvrir les nouvelles fonctionnalités lorsqu'ils en ont besoin et une documentation publiée suffisamment tard afin que la technologie en question soit suffisamment mature et stable afin que la documentation n'ait pas à être réécrite constamment ou à être supprimée rapidement suite à des changements de rupture dans les spécifications.

+ +

En général, le seuil pour déclencher la documentation d'une nouvelle technologie web correspond au moment où :

+ +

« La fonctionnalité est en voie de standardisation et implémentée quelque part. »

+ +

Une nouvelle technologie mérite sans doute d'être documentée si :

+ + + +

Il faut prendre ses précautions quant à la documentation d'une nouvelle technologie si :

+ + + +

Une nouvelle technologie ne doit pas être documentée si :

+ + + +

Conventions

+ +

Lors du retrait d'une fonctionnalité de la spécification

+ +

Il arrive parfois, pendant le développement d'une spécification et au fur à et mesure de l'évolution de standards évolutifs que de nouveaux éléments, de nouvelles méthodes ou propriétés ou autres soient ajoutés à la spécification, y restent pendant quelque temps avant d'être retirés. Cela arrive parfois rapidement et peut aussi prendre plusieurs mois ou années avant que la suppression soit effectuée. Gérer cette suppression dans la documentation peut alors s'avérer délicat. Voici quelques lignes directrices pour vous aider à décider de ce qu'il faut faire.

+ +
+

Note : Pour la suite de cette discussion, le terme « élément » sera utilisé de façon générique pour indique n'importe quel objet qui peut faire partie d'une spécification : un élément, un attribut d'un élément, une interface, une méthode spécifique, une propriété, un membre d'une interface, etc.

+
+ + + +

Les formulations exactes des avertissements et autres messages doivent être adaptées si besoin. En cas de doute sur la formulation, n'hésitez pas à vous rendre sur le canal MDN sur Matrix ou sur le forum de discussion Discourse.

+ +

Copier du contenu d'une source tierce sur MDN

+ +

Il existe souvent du contenu utile sur un sujet donné en dehors de MDN. Toutefois, copier ce contenu peut s'accompagner de pénalités légales ou techniques.

+ +

Sur le plan technique, les moteurs de recherche ont tendance à pénaliser le classement d'un site qui reproduit du contenu existant par ailleurs. Il est donc préférable d'avoir du contenu original sur MDN pour veiller au bon référencement. On peut tout à fait ajouter des liens vers du contenu externe.

+ +

Sur le plan légal, il faut être autorisé à contribuer au contenu et il doit être sous une licence et une attribution compatible avec celle de MDN.

+ + + +

Comment indiquer un conflit de spécification

+ +

Il arrive (rarement) qu'il y ait un conflit entre les différentes versions d'une spécification (généralement pour celles du W3C et du WHATWG). Par exemple, une des spécifications peut indiquer une fonctionnalité comme dépréciée tandis que l'autre n'indique pas cet état. Dans ces cas, on étudiera le comportement réel des navigateurs et on écrira une note afin d'indiquer cet état. Ainsi, en janvier 2019, l'attribut global inputmode était touché par un conflit de spécification qui était indiqué ainsi sur la page :

+ +
+

Attention : Conflit de spécification : La spécification WHATWG liste l'attribut inputmode et les navigateurs travaillent à son implémentation. La spécification W3C HTML 5.2 ne le mentionne plus en revanche (ce qui indique qu'il est considéré comme obsolète). Jusqu'à ce qu'un consensus soit atteint, on pourra considérer que c'est la définition du WHATWG qui est correcte.

+
diff --git a/files/fr/mdn/guidelines/does_this_belong_on_mdn/index.html b/files/fr/mdn/guidelines/does_this_belong_on_mdn/index.html deleted file mode 100644 index a2355886d6..0000000000 --- a/files/fr/mdn/guidelines/does_this_belong_on_mdn/index.html +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: Ceci a-t-il sa place sur MDN ? -slug: MDN/Guidelines/Does_this_belong_on_MDN -tags: - - Guide - - Guidelines - - MDN Meta -translation_of: MDN/Guidelines/Does_this_belong_on_MDN ---- -
{{MDNSidebar}}
- -

Dans cet article, nous verrons comment décider de si un sujet ou un type de contenu doit être documenté sur MDN. Nous verrons également les autres emplacements où ce contenu pourra résider.

- -

La question

- -

Si vous préparez la documentation d'un sujet, vous vous demandez peut-être si sa place est sur MDN. Vous envisagez peut-être de maintenir la documentation dans votre code source ou de publier sur le wiki de Mozilla ou dans les fichiers README d'un dépôt Git. Voyons quelles sont les meilleures options pour votre contenu.

- -

Les deux aspects principaux qui permettent de déterminer si un contenu a sa place sur MDN sont :

- - - -

Attention, toute contribution à MDN s'inscrit avec des licences open source. Celles-ci sont décrites en détail dans notre page À propos de MDN.

- -
-

Note : Les Conditions d'utilisation des sites web et de communication de Mozilla s'appliquent lorsque vous contribuez à MDN. Lisez ce document pour connaître ce qui peut et ce qui ne peut pas être publié sur les sites de Mozilla.

-
- -

Ce qui a sa place sur MDN

- -

En général, MDN est utilisé pour documenter les technologies web open source. Cela comprend toute fonctionnalité qui peut être utilisée par les développeuses et développeurs web afin de créer des sites et des applications web. S'il s'agit d'une fonctionnalité implémentée par plusieurs navigateurs et spécifiée de façon standard ou en voie de standardisation, alors sa documentation a pleinement sa place sur MDN. S'il s'agit d'une fonctionnalité expérimentale et qui n'est pas implémentée dans plusieurs navigateurs ou qui est sujette à modification alors elle pourra être documentée mais ne sera pas forcément priorisée.

- -

Les sujets majeurs de MDN sont les technologies web côté client :

- - - -
-

Note : Les technologies côté serveur sont généralement documentées autre part et cette documentation n'est pas remplacée par MDN, mais il existe quelques exceptions.

-
- -

Les sujets relatifs au développement web et qui portent sur différentes technologies sont également les bienvenus sur MDN :

- - - -
-

Note : MDN documente certaines fonctionnalités non-standard lorsqu'elles sont exposées sur le Web et que leur usage est important (comme les propriétés CSS spécifiques à WebKit par exemple). MDN documente également certaines technologies standard, hors du Web, si celles-ci s'avèrent utiles aux développeuses et développeurs web : voir la section sur les technologies connexes au Web.

-
- -

Ce qui n'a pas sa place sur MDN

- -

De façon générale, tout ce qui n'est pas décrit par un standard ouvert du Web n'appartient pas à MDN. Cette section indique quelques règles complémentaires.

- -

Produits Mozilla

- -

Le contenu de MDN portait auparavant également sur les produits de Mozilla. Cette documentation a été migrée vers d'autres projets :

- - - -

Quoi d'autre ?

- -

Voici d'autres exemples de sujets inappropriés pour MDN :

- - \ No newline at end of file diff --git a/files/fr/mdn/guidelines/does_this_belong_on_mdn/index.md b/files/fr/mdn/guidelines/does_this_belong_on_mdn/index.md new file mode 100644 index 0000000000..a2355886d6 --- /dev/null +++ b/files/fr/mdn/guidelines/does_this_belong_on_mdn/index.md @@ -0,0 +1,87 @@ +--- +title: Ceci a-t-il sa place sur MDN ? +slug: MDN/Guidelines/Does_this_belong_on_MDN +tags: + - Guide + - Guidelines + - MDN Meta +translation_of: MDN/Guidelines/Does_this_belong_on_MDN +--- +
{{MDNSidebar}}
+ +

Dans cet article, nous verrons comment décider de si un sujet ou un type de contenu doit être documenté sur MDN. Nous verrons également les autres emplacements où ce contenu pourra résider.

+ +

La question

+ +

Si vous préparez la documentation d'un sujet, vous vous demandez peut-être si sa place est sur MDN. Vous envisagez peut-être de maintenir la documentation dans votre code source ou de publier sur le wiki de Mozilla ou dans les fichiers README d'un dépôt Git. Voyons quelles sont les meilleures options pour votre contenu.

+ +

Les deux aspects principaux qui permettent de déterminer si un contenu a sa place sur MDN sont :

+ + + +

Attention, toute contribution à MDN s'inscrit avec des licences open source. Celles-ci sont décrites en détail dans notre page À propos de MDN.

+ +
+

Note : Les Conditions d'utilisation des sites web et de communication de Mozilla s'appliquent lorsque vous contribuez à MDN. Lisez ce document pour connaître ce qui peut et ce qui ne peut pas être publié sur les sites de Mozilla.

+
+ +

Ce qui a sa place sur MDN

+ +

En général, MDN est utilisé pour documenter les technologies web open source. Cela comprend toute fonctionnalité qui peut être utilisée par les développeuses et développeurs web afin de créer des sites et des applications web. S'il s'agit d'une fonctionnalité implémentée par plusieurs navigateurs et spécifiée de façon standard ou en voie de standardisation, alors sa documentation a pleinement sa place sur MDN. S'il s'agit d'une fonctionnalité expérimentale et qui n'est pas implémentée dans plusieurs navigateurs ou qui est sujette à modification alors elle pourra être documentée mais ne sera pas forcément priorisée.

+ +

Les sujets majeurs de MDN sont les technologies web côté client :

+ + + +
+

Note : Les technologies côté serveur sont généralement documentées autre part et cette documentation n'est pas remplacée par MDN, mais il existe quelques exceptions.

+
+ +

Les sujets relatifs au développement web et qui portent sur différentes technologies sont également les bienvenus sur MDN :

+ + + +
+

Note : MDN documente certaines fonctionnalités non-standard lorsqu'elles sont exposées sur le Web et que leur usage est important (comme les propriétés CSS spécifiques à WebKit par exemple). MDN documente également certaines technologies standard, hors du Web, si celles-ci s'avèrent utiles aux développeuses et développeurs web : voir la section sur les technologies connexes au Web.

+
+ +

Ce qui n'a pas sa place sur MDN

+ +

De façon générale, tout ce qui n'est pas décrit par un standard ouvert du Web n'appartient pas à MDN. Cette section indique quelques règles complémentaires.

+ +

Produits Mozilla

+ +

Le contenu de MDN portait auparavant également sur les produits de Mozilla. Cette documentation a été migrée vers d'autres projets :

+ + + +

Quoi d'autre ?

+ +

Voici d'autres exemples de sujets inappropriés pour MDN :

+ + \ No newline at end of file diff --git a/files/fr/mdn/guidelines/editorial/index.html b/files/fr/mdn/guidelines/editorial/index.html deleted file mode 100644 index ffd2cc922c..0000000000 --- a/files/fr/mdn/guidelines/editorial/index.html +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Règles éditoriales -slug: MDN/Guidelines/Editorial -tags: - - Documentation - - MDN - - MDN Meta - - Writing -translation_of: MDN/Guidelines/Editorial ---- -
{{MDNSidebar}}
- -

Cet article décrit les règles définies par l'équipe MDN pour le contenu de MDN. Toute personne qui contribue à MDN se doit de respecter ces règles.

- -

Pertinence

- -

Le contenu de MDN doit être pertinent par rapport à la section dans laquelle il apparaît. Le spam et les publicités ou tout autre contenu inapproprié ne sera jamais accepté. Les personnes qui éditent afin d'ajouter ce type de contenu pourront être bannies sans avertissement.

- -

Les liens sortants vers des sites commerciaux mais qui sont pertinents pour le sujet seront examinés au cas par cas. Leur valeur ajoutée à destination des développeuses et développeurs web doit dépasser le bénéfice commercial que tirera le site cible.

- -

Neutralité

- -

Le contenu d'un article de MDN doit conserver un point de vue neutre et les différences entre les navigateurs doivent être documentées sans biais. Les commentaires subjectifs et péjoratifs à propos d'un navigateur ou d'un agent utilisateur en particulier ne sont pas acceptables.

- -

Web ouvert

- -

MDN contient des documentations agnostiques aux différents navigateurs afin de permettre aux développeuses et développeurs web d'écrire du code qui fonctionne dans les différents navigateurs.

- -

Les technologies documentées sur MDN doivent a minima être en voie de standardisation et être implémentée par au moins un navigateur. Les différences de compatibilité sont documentées dans les tableaux de compatibilité des articles.

- -

Structure

- -

Les pages de référence doivent suivre la même structure que les autres pages du même type. Voir les types de page pour une liste d'exemple des structures communément utilisées sur MDN.

- -

Règles générales

- -

Les contributrices et contributeurs doivent suivre les lignes directrices de MDN quant au style d'écriture, aux exemples de code, etc.

diff --git a/files/fr/mdn/guidelines/editorial/index.md b/files/fr/mdn/guidelines/editorial/index.md new file mode 100644 index 0000000000..ffd2cc922c --- /dev/null +++ b/files/fr/mdn/guidelines/editorial/index.md @@ -0,0 +1,37 @@ +--- +title: Règles éditoriales +slug: MDN/Guidelines/Editorial +tags: + - Documentation + - MDN + - MDN Meta + - Writing +translation_of: MDN/Guidelines/Editorial +--- +
{{MDNSidebar}}
+ +

Cet article décrit les règles définies par l'équipe MDN pour le contenu de MDN. Toute personne qui contribue à MDN se doit de respecter ces règles.

+ +

Pertinence

+ +

Le contenu de MDN doit être pertinent par rapport à la section dans laquelle il apparaît. Le spam et les publicités ou tout autre contenu inapproprié ne sera jamais accepté. Les personnes qui éditent afin d'ajouter ce type de contenu pourront être bannies sans avertissement.

+ +

Les liens sortants vers des sites commerciaux mais qui sont pertinents pour le sujet seront examinés au cas par cas. Leur valeur ajoutée à destination des développeuses et développeurs web doit dépasser le bénéfice commercial que tirera le site cible.

+ +

Neutralité

+ +

Le contenu d'un article de MDN doit conserver un point de vue neutre et les différences entre les navigateurs doivent être documentées sans biais. Les commentaires subjectifs et péjoratifs à propos d'un navigateur ou d'un agent utilisateur en particulier ne sont pas acceptables.

+ +

Web ouvert

+ +

MDN contient des documentations agnostiques aux différents navigateurs afin de permettre aux développeuses et développeurs web d'écrire du code qui fonctionne dans les différents navigateurs.

+ +

Les technologies documentées sur MDN doivent a minima être en voie de standardisation et être implémentée par au moins un navigateur. Les différences de compatibilité sont documentées dans les tableaux de compatibilité des articles.

+ +

Structure

+ +

Les pages de référence doivent suivre la même structure que les autres pages du même type. Voir les types de page pour une liste d'exemple des structures communément utilisées sur MDN.

+ +

Règles générales

+ +

Les contributrices et contributeurs doivent suivre les lignes directrices de MDN quant au style d'écriture, aux exemples de code, etc.

diff --git a/files/fr/mdn/guidelines/index.html b/files/fr/mdn/guidelines/index.html deleted file mode 100644 index 8b9ef2e3b1..0000000000 --- a/files/fr/mdn/guidelines/index.html +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Guides du style et du contenu MDN -slug: MDN/Guidelines -tags: - - Guidelines - - Landing - - MDN Meta -translation_of: MDN/Guidelines ---- -
{{MDNSidebar}}
- -

Ces guides fournissent des détails sur la manière de rédiger et de présenter la documentation MDN, mais également sur la façon dont les extraits de code et le contenu en général devraient être présentés. En respectant ces guides, vous vous assurez que ce que vous produisez est propre et facile à utiliser.

- -

{{LandingPageListSubpages}}

diff --git a/files/fr/mdn/guidelines/index.md b/files/fr/mdn/guidelines/index.md new file mode 100644 index 0000000000..8b9ef2e3b1 --- /dev/null +++ b/files/fr/mdn/guidelines/index.md @@ -0,0 +1,14 @@ +--- +title: Guides du style et du contenu MDN +slug: MDN/Guidelines +tags: + - Guidelines + - Landing + - MDN Meta +translation_of: MDN/Guidelines +--- +
{{MDNSidebar}}
+ +

Ces guides fournissent des détails sur la manière de rédiger et de présenter la documentation MDN, mais également sur la façon dont les extraits de code et le contenu en général devraient être présentés. En respectant ces guides, vous vous assurez que ce que vous produisez est propre et facile à utiliser.

+ +

{{LandingPageListSubpages}}

diff --git a/files/fr/mdn/guidelines/video/index.html b/files/fr/mdn/guidelines/video/index.html deleted file mode 100644 index 5cdc746163..0000000000 --- a/files/fr/mdn/guidelines/video/index.html +++ /dev/null @@ -1,230 +0,0 @@ ---- -title: Contenu vidéo sur MDN -slug: MDN/Guidelines/Video -tags: - - Guidelines - - Meta - - Video -translation_of: MDN/Guidelines/Video ---- -
{{MDNSidebar}}
- -

MDN n'est pas un site contenant beaucoup de vidéos. Toutefois, certaines documentations sont propices à ce type de média. Dans cet article, nous verrons quand inclure des vidéos sur MDN et quelques conseils permettant de créer des vidéos simples et efficaces.

- -

Quand utiliser des vidéos sur MDN

- -

L'utilisation de vidéo pour de la documentation technique n'est pas indiquée par défaut pour plusieurs raisons :

- - - -
-

Note : Il est important de garder ces limitations en tête lorsqu'on réalise des vidéos afin de les minimiser autant que possible.

-
- -

Il existe de nombreux sites populaires qui fournissent de nombreux tutoriels vidéo. MDN n'est pas un site dont la majorité du contenu est de la vidéo, toutefois, il est possible d'intégrer des vidéos dans certains articles MDN selon le contexte.

- -

Sur MDN, les vidéos sont particulièrement utilisées lorsqu'on souhaite décrire une suite d'instruction ou un procédé en plusieurs étapes qu'il serait difficile d'exprimer de façon concise avec du texte. Cela s'avère notamment utile lorsqu'on tente de décrire des procédés qui utilisent plusieurs applications ou fenêtres et qui incluent des interactions avec l'interface graphique qui pourraient ne pas être simples à décrire : « maintenant, cliquez sur le bouton situé en haut à gauche et qui ressemble à un canard ».

- -

Dans de telles situations, il est souvent plus pratique de montrer ce qu'on indique.

- -

À quoi doit ressembler une vidéo sur MDN ?

- -

Une vidéo à destination de MDN devrait être :

- - - -

Pour expliquer quelque chose de complexes, on pourra utiliser un ensemble de vidéos courtes et de captures d'écran avec du texte. Le texte permettra ainsi d'insister sur les notions vues dans les vidéos et la personne qui consulte le contenu pourra alors choisir de suivre le texte et/ou la vidéo.

- -

De plus, on fera attention aux conseils suivants :

- - - -

Outils

- -

Il vous faudra un outil pour enregistrer la vidéo. Il en existe une variété allant d'outils gratuits à payants, de simples à complexes. Si vous avez déjà créé du contenu vidéo : parfait. Sinon, nous vous conseillons de commencer avec un outil simple puis de choisir ensuite quelque chose de plus complexe si besoin.

- -

Le tableau qui suit fournit quelques recommandations d'outils pour commencer.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
OutilSystème d'exploitationCoûtFonctionnalités de post-production ?
Open Broadcaster SoftwaremacOS, Windows, LinuxGratuitOui
CamStudioWindowsGratuitLimitées
CamtasiaWindows, macOSÉlevéOui
QuickTime PlayermacOSGratuitAucune
ScreenFlowmacOSIntermédiaireOui
KazamLinuxGratuitMinimales
- -

Conseils pour QuickTime

- -

Si vous utilisez macOS, Quicktime Player est disponible et dispose de quelques fonctionnalités pour l'enregistrement :

- -
    -
  1. Choisissez Fichier > Nouvel enregistrement d'écran à partir du menu principal.
    2. -
  2. Dans la boîte Enregistrement d'écran, utilisez le bouton d'enregistrement (le bouton rouge).
    3. -
  3. Dessinez un rectangle sur la zone de l'écran que vous souhaitez enregistrer.
    4. -
  4. Appuyez sur le bouton Démarrer l'enregistrement.
    5. -
  5. Effectuez les actions que vous souhaitez enregistrer.
    6. -
  6. Appuyez sur le bouton Stop.
    7. -
  7. Choisissez Fichier > Exporter en tant que… > 1080p à partir du menu principal afin d'avoir une définition suffisamment élevée.
    8. -
- -

Autres ressources

- - - -

Étapes de création d'une vidéo

- -

Les sections qui suivent décrivent les étapes principales à suivre pour créer une vidéo et l'intégrer à une page MDN.

- -

Préparation

- -

Tout d'abord, planifiez la suite d'actions que vous souhaitez enregistrer et choisissez les meilleures façons de commencer et de finir.

- -

Assurez vous que votre arrière-plan de bureau et votre profil de navigateur soient vierges. Planifier les tailles et le positionnement des fenêtres, notamment si vous utilisez plusieurs fenêtres.

- -

Planifiez soigneusement les étapes que vous allez enregistrer et pratiquez cette séquence d'actions plusieurs fois avant d'enregistrer :

- - - -
-

Note : Ne zoomez pas au point que les éléments d'interfaces soient déformés ou semblent étranges.

-
- -

Enregistrement

- -

Lorsque vous enregistrez, avancez dans les étapes de façon calme et régulière. Effectuez des pauses d'une seconde ou deux aux moments importants (lorsqu'il faut cliquer sur un bouton par exemple) et assurez vous que le pointeur de la souris n'occulte pas d'icône ou de texte important.

- -

N'oubliez pas de faire une pause d'une ou deux secondes à la fin pour montrer le résultat final de la séquence d'actions.

- -
-

Note : Si vous utilisez un outil simple comme QuickTime Player ou que vous ne pouvez pas effectuer de post-production, veillez à ce que la taille de la fenêtre soit de la bonne taille pour ce que vous voulez montrer.

-
- -

Post-production

- -

En post-production, vous pourrez mettre en avant certains éléments notamment grâce à :

- - - -

Mettez en avant les moments-clés et les détails difficiles à voir comme les clics sur une icône donnée ou la saisie d'une URL particulière. La mise en avant doit durer au moins 1 à 2 secondes et il sera généralement utile d'ajouter une courte transition (200 à 300 millisecondes) au début et à la fin de la mise en évidence.

- -

Attention à ne pas abuser de ces effets, on ne veut pas que les spectateurs aient le mal de mer à force de voir des zooms/dézooms.

- -

Si besoin, redimensionnez la vidéo aux proportions souhaitées.

- -

Upload

- -

Actuellement, les vidéos doivent être uploadées sur YouTube afin d'être affichées sur MDN.

- -
-

Note : Marquez la vidéo en « non répertoriée » si celle-ci n'a pas de sens particulier en dehors du contexte de la page MDN.

-
- -

Intégration

- -

Une fois la vidéo uploadée, vous pouvez intégrer la vidéo à la page avec la macro {{TemplateLink("EmbedYouTube")}}. Elle permet d'insérer la vidéo à l'emplacement de la macro :

- -

\{{EmbedYouTube("you-tube-url-slug")}}

- -

Cette macro utilise un seul argument qui correspond à la fin de l'URL de la vidéo. Ainsi, pour afficher la vidéo disponible à l'URL https://www.youtube.com/watch?v=ELS2OOUvxIw, on appellera la macro ainsi :

- -

\{{EmbedYouTube("ELS2OOUvxIw")}}

diff --git a/files/fr/mdn/guidelines/video/index.md b/files/fr/mdn/guidelines/video/index.md new file mode 100644 index 0000000000..5cdc746163 --- /dev/null +++ b/files/fr/mdn/guidelines/video/index.md @@ -0,0 +1,230 @@ +--- +title: Contenu vidéo sur MDN +slug: MDN/Guidelines/Video +tags: + - Guidelines + - Meta + - Video +translation_of: MDN/Guidelines/Video +--- +
{{MDNSidebar}}
+ +

MDN n'est pas un site contenant beaucoup de vidéos. Toutefois, certaines documentations sont propices à ce type de média. Dans cet article, nous verrons quand inclure des vidéos sur MDN et quelques conseils permettant de créer des vidéos simples et efficaces.

+ +

Quand utiliser des vidéos sur MDN

+ +

L'utilisation de vidéo pour de la documentation technique n'est pas indiquée par défaut pour plusieurs raisons :

+ + + +
+

Note : Il est important de garder ces limitations en tête lorsqu'on réalise des vidéos afin de les minimiser autant que possible.

+
+ +

Il existe de nombreux sites populaires qui fournissent de nombreux tutoriels vidéo. MDN n'est pas un site dont la majorité du contenu est de la vidéo, toutefois, il est possible d'intégrer des vidéos dans certains articles MDN selon le contexte.

+ +

Sur MDN, les vidéos sont particulièrement utilisées lorsqu'on souhaite décrire une suite d'instruction ou un procédé en plusieurs étapes qu'il serait difficile d'exprimer de façon concise avec du texte. Cela s'avère notamment utile lorsqu'on tente de décrire des procédés qui utilisent plusieurs applications ou fenêtres et qui incluent des interactions avec l'interface graphique qui pourraient ne pas être simples à décrire : « maintenant, cliquez sur le bouton situé en haut à gauche et qui ressemble à un canard ».

+ +

Dans de telles situations, il est souvent plus pratique de montrer ce qu'on indique.

+ +

À quoi doit ressembler une vidéo sur MDN ?

+ +

Une vidéo à destination de MDN devrait être :

+ + + +

Pour expliquer quelque chose de complexes, on pourra utiliser un ensemble de vidéos courtes et de captures d'écran avec du texte. Le texte permettra ainsi d'insister sur les notions vues dans les vidéos et la personne qui consulte le contenu pourra alors choisir de suivre le texte et/ou la vidéo.

+ +

De plus, on fera attention aux conseils suivants :

+ + + +

Outils

+ +

Il vous faudra un outil pour enregistrer la vidéo. Il en existe une variété allant d'outils gratuits à payants, de simples à complexes. Si vous avez déjà créé du contenu vidéo : parfait. Sinon, nous vous conseillons de commencer avec un outil simple puis de choisir ensuite quelque chose de plus complexe si besoin.

+ +

Le tableau qui suit fournit quelques recommandations d'outils pour commencer.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OutilSystème d'exploitationCoûtFonctionnalités de post-production ?
Open Broadcaster SoftwaremacOS, Windows, LinuxGratuitOui
CamStudioWindowsGratuitLimitées
CamtasiaWindows, macOSÉlevéOui
QuickTime PlayermacOSGratuitAucune
ScreenFlowmacOSIntermédiaireOui
KazamLinuxGratuitMinimales
+ +

Conseils pour QuickTime

+ +

Si vous utilisez macOS, Quicktime Player est disponible et dispose de quelques fonctionnalités pour l'enregistrement :

+ +
    +
  1. Choisissez Fichier > Nouvel enregistrement d'écran à partir du menu principal.
    2. +
  2. Dans la boîte Enregistrement d'écran, utilisez le bouton d'enregistrement (le bouton rouge).
    3. +
  3. Dessinez un rectangle sur la zone de l'écran que vous souhaitez enregistrer.
    4. +
  4. Appuyez sur le bouton Démarrer l'enregistrement.
    5. +
  5. Effectuez les actions que vous souhaitez enregistrer.
    6. +
  6. Appuyez sur le bouton Stop.
    7. +
  7. Choisissez Fichier > Exporter en tant que… > 1080p à partir du menu principal afin d'avoir une définition suffisamment élevée.
    8. +
+ +

Autres ressources

+ + + +

Étapes de création d'une vidéo

+ +

Les sections qui suivent décrivent les étapes principales à suivre pour créer une vidéo et l'intégrer à une page MDN.

+ +

Préparation

+ +

Tout d'abord, planifiez la suite d'actions que vous souhaitez enregistrer et choisissez les meilleures façons de commencer et de finir.

+ +

Assurez vous que votre arrière-plan de bureau et votre profil de navigateur soient vierges. Planifier les tailles et le positionnement des fenêtres, notamment si vous utilisez plusieurs fenêtres.

+ +

Planifiez soigneusement les étapes que vous allez enregistrer et pratiquez cette séquence d'actions plusieurs fois avant d'enregistrer :

+ + + +
+

Note : Ne zoomez pas au point que les éléments d'interfaces soient déformés ou semblent étranges.

+
+ +

Enregistrement

+ +

Lorsque vous enregistrez, avancez dans les étapes de façon calme et régulière. Effectuez des pauses d'une seconde ou deux aux moments importants (lorsqu'il faut cliquer sur un bouton par exemple) et assurez vous que le pointeur de la souris n'occulte pas d'icône ou de texte important.

+ +

N'oubliez pas de faire une pause d'une ou deux secondes à la fin pour montrer le résultat final de la séquence d'actions.

+ +
+

Note : Si vous utilisez un outil simple comme QuickTime Player ou que vous ne pouvez pas effectuer de post-production, veillez à ce que la taille de la fenêtre soit de la bonne taille pour ce que vous voulez montrer.

+
+ +

Post-production

+ +

En post-production, vous pourrez mettre en avant certains éléments notamment grâce à :

+ + + +

Mettez en avant les moments-clés et les détails difficiles à voir comme les clics sur une icône donnée ou la saisie d'une URL particulière. La mise en avant doit durer au moins 1 à 2 secondes et il sera généralement utile d'ajouter une courte transition (200 à 300 millisecondes) au début et à la fin de la mise en évidence.

+ +

Attention à ne pas abuser de ces effets, on ne veut pas que les spectateurs aient le mal de mer à force de voir des zooms/dézooms.

+ +

Si besoin, redimensionnez la vidéo aux proportions souhaitées.

+ +

Upload

+ +

Actuellement, les vidéos doivent être uploadées sur YouTube afin d'être affichées sur MDN.

+ +
+

Note : Marquez la vidéo en « non répertoriée » si celle-ci n'a pas de sens particulier en dehors du contexte de la page MDN.

+
+ +

Intégration

+ +

Une fois la vidéo uploadée, vous pouvez intégrer la vidéo à la page avec la macro {{TemplateLink("EmbedYouTube")}}. Elle permet d'insérer la vidéo à l'emplacement de la macro :

+ +

\{{EmbedYouTube("you-tube-url-slug")}}

+ +

Cette macro utilise un seul argument qui correspond à la fin de l'URL de la vidéo. Ainsi, pour afficher la vidéo disponible à l'URL https://www.youtube.com/watch?v=ELS2OOUvxIw, on appellera la macro ainsi :

+ +

\{{EmbedYouTube("ELS2OOUvxIw")}}

diff --git a/files/fr/mdn/guidelines/writing_style_guide/index.html b/files/fr/mdn/guidelines/writing_style_guide/index.html deleted file mode 100644 index 348cec2bc7..0000000000 --- a/files/fr/mdn/guidelines/writing_style_guide/index.html +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: Guide stylistique -slug: MDN/Guidelines/Writing_style_guide -tags: - - Documentation - - Guide - - Guidelines - - MDN - - MDN Meta - - MDN Web Docs - - MDN style guide - - Style guide - - Writing style guide -translation_of: MDN/Guidelines/Writing_style_guide ---- -
{{MDNSidebar}}
- -

Afin de présenter la documentation de façon organisée, cohérente et facile à lire, le guide stylistique de MDN décrit la façon dont le texte doit être organisé, orthographié, mis en forme, etc. Il s'agit ici de règles générales plutôt que de consignes strictes. Le contenu importe plus que la forme et il n'y a pas d'obligation à apprendre ce guide avant de contribuer. Toutefois, ne soyez pas surpris⋅e si une contributrice ou un contributeur édite une de vos éditions pour respecter ce guide.

- -

La suite de ce guide vise avant tout la documentation francophone. Elle reprend des parties du guide stylistique anglophone lorsque c'est pertinent. Vous pouvez également consulter le guide stylistique de la communauté francophone. Si vous souhaitez contribuer au contenu en anglais, rapportez vous au guide stylistique anglophone.

- -

Règles de base

- -

Voici quelques règles simples qui permettent de conserver une cohérence dans la documentation.

- -

Titres des pages

- -

Les titres des pages sont utilisés dans les résultats des recherches et affichés dans les fils d'Ariane en haut de la page. Le titre de la page pourra être différent de la partie d'URL du document. En français, il devra l'être (car le fragment d'URL sera anglophone).

- -

Titres et capitales

- -

Seul le premier terme d'un titre (de page ou de section) devra être en capitale :

- - - -

Si vous voyez certains titres qui enfreignent cette règle, n'hésitez pas à contribuer pour les corriger.

- -

Choix des titres

- -

Contrairement au fragment d'URL de la page (court et fixé par la version anglophone), on pourra choisir un titre descriptif suffisamment long.

- -

Création de nouvelles pages

- -

Le contenu francophone « suit » le contenu anglophone. Toute nouvelle page de MDN devra d'abord être créée avec sa version anglaise avant d'être traduite.

- -

Style et mise en forme des exemples de code

- -

On pourra traduire les noms de certaines variables pour les franciser (par exemple toto à la place de foo) et on traduira les commentaires

- -

Sauts de ligne

- -

Pour un fragment de code, on évitera d'avoir une ligne trop longue qui nécessite de faire défiler le contenu horizontal. On privilégiera les ruptures de lignes naturelles :

- -
if (class.CONDITION || class.OTHER_CONDITION || class.SOME_OTHER_CONDITION
-       || class.YET_ANOTHER_CONDITION ) {
-  /* quelque chose */
-}
-
-var toolkitProfileService = Components.classes["@mozilla.org/toolkit/profile-service;1"]
-                           .createInstance(Components.interfaces.nsIToolkitProfileService);
-
- -

Abréviations

- -
-

Note : les abréviations sont à utiliser à bon escient et il faudra bien connaître leur sens (notamment pour les abrévations latines) afin de les utiliser correctement. Il faut être conscient que leur usage peut être source de confusion pour les lectrices et lecteurs qui pourraient ne pas y être habitués.

-
- -

Dans les notes et parenthèses

- -

Les abréviations communes (etc., i.e.) pourront être utilisées dans les notes et entre parenthèses. Attention, on utilisera ex. plutôt que e.g. qui est usité en anglais (ou que p. ex. qui est moins usité).

- -

Dans le texte

- - - - -

Acronymes et abréviations

- -

Capitalisation et usage des points

- -

Les acronymes seront écrits en capitales et sans point.

- - - -

Explication

- -

Lors de la première mention d'un terme abrégé sur une page, on expliquera l'acronyme et/ou on liera vers le glossaire.

- -

Pluriels des acronymes

- -

Contrairement aux pratiques anglophones, on n'apportera pas de s pour les formes plurielles des acronymes.

- - - -

Ponctuation

- -

Apostrophes et guillemets

- -

On n'utilisera pas d'apostrophe courbe sur MDN. L'usage des guillemets français est autorisé (mais pas obligatoire) et ceux-ci ne doivent pas servir dans du code pour délimiter des chaînes de caractères où il faudra utiliser les doubles quotes.

- -

Orthographe

- -

On recommandera l'utilisation de Grammalecte pour vérifier l'orthographe d'un document.

- -

Terminologie

- -

En cas de doute sur la formulation en français d'un terme ou d'une expression anglaise, on privilégiera l'usage, Transvision, Wikipédia.

\ No newline at end of file diff --git a/files/fr/mdn/guidelines/writing_style_guide/index.md b/files/fr/mdn/guidelines/writing_style_guide/index.md new file mode 100644 index 0000000000..348cec2bc7 --- /dev/null +++ b/files/fr/mdn/guidelines/writing_style_guide/index.md @@ -0,0 +1,124 @@ +--- +title: Guide stylistique +slug: MDN/Guidelines/Writing_style_guide +tags: + - Documentation + - Guide + - Guidelines + - MDN + - MDN Meta + - MDN Web Docs + - MDN style guide + - Style guide + - Writing style guide +translation_of: MDN/Guidelines/Writing_style_guide +--- +
{{MDNSidebar}}
+ +

Afin de présenter la documentation de façon organisée, cohérente et facile à lire, le guide stylistique de MDN décrit la façon dont le texte doit être organisé, orthographié, mis en forme, etc. Il s'agit ici de règles générales plutôt que de consignes strictes. Le contenu importe plus que la forme et il n'y a pas d'obligation à apprendre ce guide avant de contribuer. Toutefois, ne soyez pas surpris⋅e si une contributrice ou un contributeur édite une de vos éditions pour respecter ce guide.

+ +

La suite de ce guide vise avant tout la documentation francophone. Elle reprend des parties du guide stylistique anglophone lorsque c'est pertinent. Vous pouvez également consulter le guide stylistique de la communauté francophone. Si vous souhaitez contribuer au contenu en anglais, rapportez vous au guide stylistique anglophone.

+ +

Règles de base

+ +

Voici quelques règles simples qui permettent de conserver une cohérence dans la documentation.

+ +

Titres des pages

+ +

Les titres des pages sont utilisés dans les résultats des recherches et affichés dans les fils d'Ariane en haut de la page. Le titre de la page pourra être différent de la partie d'URL du document. En français, il devra l'être (car le fragment d'URL sera anglophone).

+ +

Titres et capitales

+ +

Seul le premier terme d'un titre (de page ou de section) devra être en capitale :

+ + + +

Si vous voyez certains titres qui enfreignent cette règle, n'hésitez pas à contribuer pour les corriger.

+ +

Choix des titres

+ +

Contrairement au fragment d'URL de la page (court et fixé par la version anglophone), on pourra choisir un titre descriptif suffisamment long.

+ +

Création de nouvelles pages

+ +

Le contenu francophone « suit » le contenu anglophone. Toute nouvelle page de MDN devra d'abord être créée avec sa version anglaise avant d'être traduite.

+ +

Style et mise en forme des exemples de code

+ +

On pourra traduire les noms de certaines variables pour les franciser (par exemple toto à la place de foo) et on traduira les commentaires

+ +

Sauts de ligne

+ +

Pour un fragment de code, on évitera d'avoir une ligne trop longue qui nécessite de faire défiler le contenu horizontal. On privilégiera les ruptures de lignes naturelles :

+ +
if (class.CONDITION || class.OTHER_CONDITION || class.SOME_OTHER_CONDITION
+       || class.YET_ANOTHER_CONDITION ) {
+  /* quelque chose */
+}
+
+var toolkitProfileService = Components.classes["@mozilla.org/toolkit/profile-service;1"]
+                           .createInstance(Components.interfaces.nsIToolkitProfileService);
+
+ +

Abréviations

+ +
+

Note : les abréviations sont à utiliser à bon escient et il faudra bien connaître leur sens (notamment pour les abrévations latines) afin de les utiliser correctement. Il faut être conscient que leur usage peut être source de confusion pour les lectrices et lecteurs qui pourraient ne pas y être habitués.

+
+ +

Dans les notes et parenthèses

+ +

Les abréviations communes (etc., i.e.) pourront être utilisées dans les notes et entre parenthèses. Attention, on utilisera ex. plutôt que e.g. qui est usité en anglais (ou que p. ex. qui est moins usité).

+ +

Dans le texte

+ + + + +

Acronymes et abréviations

+ +

Capitalisation et usage des points

+ +

Les acronymes seront écrits en capitales et sans point.

+ + + +

Explication

+ +

Lors de la première mention d'un terme abrégé sur une page, on expliquera l'acronyme et/ou on liera vers le glossaire.

+ +

Pluriels des acronymes

+ +

Contrairement aux pratiques anglophones, on n'apportera pas de s pour les formes plurielles des acronymes.

+ + + +

Ponctuation

+ +

Apostrophes et guillemets

+ +

On n'utilisera pas d'apostrophe courbe sur MDN. L'usage des guillemets français est autorisé (mais pas obligatoire) et ceux-ci ne doivent pas servir dans du code pour délimiter des chaînes de caractères où il faudra utiliser les doubles quotes.

+ +

Orthographe

+ +

On recommandera l'utilisation de Grammalecte pour vérifier l'orthographe d'un document.

+ +

Terminologie

+ +

En cas de doute sur la formulation en français d'un terme ou d'une expression anglaise, on privilégiera l'usage, Transvision, Wikipédia.

\ No newline at end of file -- cgit v1.2.3-54-g00ecf