diff options
Diffstat (limited to 'files/fr/mdn/guidelines/code_guidelines/general/index.md')
| -rw-r--r-- | files/fr/mdn/guidelines/code_guidelines/general/index.md | 167 |
1 files changed, 167 insertions, 0 deletions
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 +--- +<div>{{MDNSidebar}}</div> + +<p>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.</p> + +<h2 id="In_this_article">Dans cet article</h2> + +<ul> + <li><a href="#indentation_spacing_size">Indentation, espacement, taille</a> + + <ul> + <li><a href="#indentation">Indentation</a></li> + <li><a href="#code_line_length">Longueur des lignes de code</a></li> + <li><a href="#code_block_height">Hauteur des blocs de code</a></li> + </ul> + </li> + <li><a href="#guidelines_for_displaying_examples">Directives pour l'affichage des exemples</a> + <ul> + <li><a href="#size_of_rendered_example">Taille du rendu des exemples</a></li> + <li><a href="#use_of_images_and_other_media">Utilisation d'images et d'autres médias</a></li> + <li><a href="#use_of_color">Utilisation de la couleur</a></li> + <li><a href="#highlight_good_and_bad_practice_examples">Mettre en évidence les exemples de bonnes et de mauvaises pratiques</a></li> + </ul> + </li> + <li><a href="#writing_syntax_sections_on_reference_pages">Rédaction de sections syntaxiques sur les pages de référence</a></li> +</ul> + +<h2 id="Indentation_spacing_size">Indentation, espacement, taille</h2> + +<h3 id="Indentation">Indentation</h3> + +<p>Tout le code doit utiliser 2 espaces pour l'indentation, par exemple :</p> + +<pre class="brush: html example-good"><div> + <p>C'est mon paragraphe.</p> +</div></pre> + +<pre class="brush: js example-good">function myFunc() { + if(thingy) { + console.log('Ouaip, ça a marché.'); + } +}</pre> + +<h3 id="Code_line_length">Longueur des lignes de code</h3> + +<p>Les lignes de code ne doivent pas comporter plus de 80 caractères (64 pour les <a href="https://github.com/mdn/interactive-examples">exemples interactifs</a>). Vous devez rompre les lignes de manière raisonnable pour des raisons de lisibilité, mais pas au détriment des bonnes pratiques.</p> + +<p>Par exemple, ceci n'est pas génial :</p> + +<pre class="brush: js example-bad">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.';</pre> + +<p>C'est mieux, mais un peu gênant :</p> + +<pre class="brush: js">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.';</pre> + +<p>Une meilleure solution consiste à utiliser un <i>template</i> :</p> + +<pre class="brush: js example-good">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.`;</pre> + +<h3 id="Code_block_height">Hauteur des blocs de code</h3> + +<p>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.</p> + +<h2 id="Guidelines_for_displaying_examples">Directives pour l'affichage des exemples</h2> + +<h3 id="Size_of_rendered_example">Taille du rendu des exemples</h3> + +<p>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%).</p> + +<p>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.</p> + +<p>Vous devriez également penser à rendre vos exemples plus ou moins adaptables, afin qu'ils soient également utiles sur les appareils mobiles.</p> + +<h3 id="Use_of_images_and_other_media">Utilisation d'images et d'autres médias</h3> + +<p>Parfois, vous voudrez inclure des images ou d'autres médias dans un exemple. Si vous le faites :</p> + +<ul> + <li>Assurez-vous que leur licence vous permet de les utiliser. Essayez d'utiliser des médias dont la licence est très permissive, comme <a href="https://creativecommons.org/share-your-work/public-domain/cc0/">CC0</a>, ou au moins compatible avec notre licence générale de contenu - <a href="https://creativecommons.org/licenses/by-sa/2.5/">Licence Creative Commons Attribution-ShareAlike</a> (CC-BY-SA).</li> + <li>Pour les images, faites-les passer par <a href="https://tinypng.com">https://tinypng.com</a> ou <a href="https://imageoptim.com">https://imageoptim.com</a>, pour réduire le poids de la page des exemples.</li> + <li>Pour le <code>SVG</code>, exécutez le code via <a href="https://jakearchibald.github.io/svgomg/">SVGOMG</a>, et assurez-vous que le fichier <code>SVG</code> comporte une ligne vide à la fin du fichier.</li> + <li> + <p>Lorsque vous affichez des icônes sur une page (ex. via <a href="/fr/docs/Web/CSS/background-image"><code>background-image</code></a>), utilisez les icônes du référentiel <a href="https://github.com/mdn/mdn-dinocons">mdn-dinocons</a>, le cas échéant, et essayez de correspondre à leur style dans les autres cas.</p> + </li> +</ul> + +<h3 id="Use_of_color">Utilisation de la couleur</h3> + +<p>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).</p> + +<p>Préférez utiliser des mots-clés pour les couleurs primaires et autres couleurs "de base", par exemple :</p> + +<pre class="brush: css example-good"> +color: black; +color: white; +color: red; +</pre> + +<p>Utilisez rgb() pour des couleurs plus complexes (y compris les couleurs semi-transparentes) :</p> + +<pre class="brush: css example-good"> +color: rgb(0, 0, 0, 0.5); +color: rgb(248, 242, 230); +</pre> + +<p>Si vous devez utiliser des couleurs hexadécimales, utilisez des minuscules :</p> + +<pre class="brush: css example-good"> +color: #058ed9; +color: #a39a92; +</pre> + +<p>et utilisez la forme abrégée le cas échéant :</p> + +<pre class="brush: css example-good"> +color: #ff0; +color: #fff; +</pre> + +<p>Le fichier <a href="https://github.com/mdn/mdn-minimalist/blob/main/sass/vars/_color-palette.scss">sass/vars/_color-palette.scss</a> du dépôt <a href="https://github.com/mdn/mdn-minimalist">mdn-minimalist</a> comporte un ensemble de couleurs utiles qui complètent le design général de MDN.</p> + +<h3 id="Highlight_good_and_bad_practice_examples">Mettre en évidence les exemples de bonnes et de mauvaises pratiques</h3> + +<p>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.</p> + +<p>Pour ce faire, vous devez d'abord utiliser les commandes de l'éditeur MDN pour placer votre bloc de code dans un bloc <code><pre></code> et lui donner la coloration syntaxique appropriée. La source du code ressemblera à quelque chose comme ceci :</p> + +<pre class="brush: js"> +function myFunc() { + console.log('Hello!'); +}; +</pre> +</pre> + +<p>Pour en faire un bon exemple, vous insérez <code>example-good</code> juste avant le guillemet fermant de l'attribut <code>class</code> :</p> + +<pre class="brush: html"><pre class="brush: js example-good"> + ... +</pre> + +<p>Pour en faire un mauvais exemple, vous insérez <code>example-bad</code> juste avant le guillemet fermant de l'attribut <code>class</code> :</p> + +<pre class="brush: html"><pre class="brush: js example-bad"> + ... +</pre> + +<p>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.</p> + +<h2 id="Writing_syntax_sections_on_reference_pages">Rédaction de sections syntaxiques sur les pages de référence</h2> + +<p>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 <a href="/fr/docs/MDN/Structures/Syntax_sections">Sections syntaxiques</a>.</p> |