JavaScript Standard Style

Guide de style JavaScript, avec linteur, et formateur

Ce module vous laisse gagner du temps de trois façons:

Pas de configuration. La façon la plus facile d'assurer un style consistant dans vos projets. Aucune décision à prendre. Aucun fichier .eslintrc à gérer.
Formatte le code automatiquement. Exécutez standard --fix et dites au revoir aux irrégularités dans votre code.
Identifiez en avance les erreurs et problèmes de styles. Gagnez un temps précieux de revision du code en eliminant les échanges entre le contributeur et le réviseur.

Essayez-le dès maintenant en exécutant npx standard --fix

Installation

La façon la plus facile d'utiliser le JavaScript Standard Style est de l'installer globalement comme un programme Node de ligne de commande. Exécutez la commande qui suit dans le Terminal:

$ npm install standard --global

Ou, vous pouvez installer standard localement, pour l'utiliser dans un seul projet:

$ npm install standard --save-dev

Note: Pour executer les commandes précédentes, Node.js et npm doivent être installés.

Utilisation

Apres avoir installé standard, vous devriez pouvoir l'utiliser. Le cas le plus facile serait de verifier le style de tous les fichiers JavaScript dans le dossier actuellement utilisé:

$ standard
Error: Use JavaScript Standard Style
  lib/torrent.js:950:11: Expected '===' and instead saw '=='.

Vous pouvez passer en option un dossier (ou dossiers) en utilisant la structure glob. Soyez surs d'entourer les chemins de fichier qui contiennent des structures glob avec des guillemets pour qu'ils soient interprétés par standard et pas votre shell:

$ standard "src/util/**/*.js" "test/**/*.js"

Note: par default standard va chercher tous les fichiers qui correspondent à: **/*.js, **/*.jsx.

Ce que vous pouvez faire si vous êtes malins

Ajoutez le au fichier package.json

{
  "name": "my-cool-package",
  "devDependencies": {
    "standard": "*"
  },
  "scripts": {
    "test": "standard && node my-tests.js"
  }
}

Le style est vérifié automatiquement quand vous executez npm test

$ npm test
Error: Use JavaScript Standard Style
  lib/torrent.js:950:11: Expected '===' and instead saw '=='.

Ne demandez plus jamais de changement de style dans une PR!

Pourquoi devrais-je utiliser le JavaScript Standard Style?

La beauté du JavaScript Standard Style est dans sa simplicité. Personne ne veut maintenir des fichiers de configuration de style de plusieurs centaines de lignes pour chaque module/projet sur lesquels vous travaillez!

Ce module vous laisse gagner du temps de trois façons:

Pas de configuration. La façon la plus facile d'assurer un style consistant dans vos projets.
Formatte le code automatiquement. Exécutez standard --fix et dites au revoir aux irregularités dans votre code.
Identifiez en avance les erreurs et problèmes de styles. Gagnez un temps precieux de revision du code en éliminant les échanges entre le contributeur et le réviseur.

Adopter le style standard c'est mettre l'importance de la clarité du code et des conventions de la communauté avant le style personel. Ça n'a peut-être pas de sens pour 100% des projets et cultures de développement, cependant, open-source peut être un environement hostile pour les jeunes développeurs. Mettre en place des attentes claires et automatisées pour les contributeurs permet un projet plus sain.

Pour plus d'information, jetez un oeil a la présentation "Write Perfect Code with Standard and ESLint". Dans cette présentation, vous allez apprendre sur le linting, quand utiliser standard contre eslint, et comment prettier compare à standard.

Qui utilise le JavaScript Standard Style?

Beaucoup de monde!

	Your logo here	Your logo here	Your logo here

En plus de ces entreprises, beaucoup de membres de la communauté utilisent standard sur des projets qui sont trop nombreux pour les lister ici.

standard est aussi le top linteur sur le showcase Clean Code linter de GitHub.

Il y a-t-il des plugins pour les éditeurs de texte?

D'abord, installez standard. Après, installez le correct plugin pour votre éditeur:

Sublime Text

En utilisant Package Control, installez Sublimelinter et Sublimelinter-contrib-standard.

Pour le formatage automatique quand vous sauvegardez, installez StandardFormat.

Atom

Installez linter-js-standard.

Autrement, vous pouvez installer linter-js-standard-engine. Au lieu de bundler une version de standard, il va automatiquement utiliser la version installée dans le project actuel. Il marchera aussi tout de suite avec d'autres linteurs basés sur standard-engine.

Pour un formatage automatique, installez standard-formatter. Pour des extraits, installez standardjs-snippets.

Visual Studio Code

Installez vscode-standard. (Cela inclus le support pour le formatage automatique.)

Pour des extraits JS, installez: vscode-standardjs-snippets. Pour des extraits React, installez vscode-react-standard.

Vim

Installez ale. Et ajoutez ces lignes dans votre fichier .vimrc.

let g:ale_linters = {
\   'javascript': ['standard'],
\}

Cela definit standard comme votre seul linteur pour les fichiers javascript et donc previent les conflits avec eslint.

Pour le formatage automatique quand vous sauvegardez, ajoutez ces lines à .vimrc:

autocmd bufwritepost *.js silent !standard --fix %
set autoread

Les plugins alternatifs à considérer incluent neomake et syntastic, les deux ont un support integré pour standard (une configuration est peut-être nécessaire).

Emacs

Installez Flycheck et jetez un oeil au manuel pour apprendre à l'utiliser dans vos projets.

Brackets

Cherchez les extensions pour "Standard Code Style" et cliquez "Install".

WebStorm (PhpStorm, IntelliJ, RubyMine, JetBrains, etc.)

WebStorm à récemment annouce le support natif pour standard directement dans l'IDE.

Si vous préférez toujours configurer standard manuellement, suivez ce guide. Cela s'applique à tous les produits JetBrains, inclus PhpStorm, IntelliJ, RubyMine, etc.

Il y a-t-il un badge readme?

Oui! Si vouz utilisez standard dans votre projet, vous pouvez inclure un de ces badges dans votre readme pour laisser les gens savoir que votre code utilise le style standard.

[![JavaScript Style Guide](https://cdn.rawgit.com/standard/standard/master/badge.svg)](https://github.com/standard/standard)

[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)

Je ne suis pas d'accord avec la règle X, pouvez-vous la changer?

Non. Le but de standard est de gagner du temps en evitant bikeshedding à propos du style de code. Il y a plein de débats en ligne à propos des tabs vs. espaces, etc. qui ne seront jamais résolus. Ces débats sont juste distractifs et empèchent de faire avancer les choses. A la fin de la journée, vouz devez faire un choix et c'est toute la philosophie derrière standard -- c'est juste un tas d'opinions pour 'faire un choix'. J'espère que les utilisateurs voient la valeur au lieu de défendre leurs propres opinions.

Si vous voulez vraiment configurer des centaines de règles ESLint vous-mêmes, vous pouvez toujours utiliser eslint directement avec eslint-config-standard pour ajouter vos changement au-dessus. standard-eject peut vous aider a changer de standard à eslint et eslint-config-standard.

Astuce pro: Utilisez juste standard et passez à autre chose. Vous pourriez passer votre temps a résoudre de vrais problèmes! :P

Ce n'est pas un vrai standard web!

Bien sur que non! Le style présenté ici n'est pas affilié à aucun groupe de standards web, ce pourquoi ce repo est appelé standard/standard et pas ECMA/standard.

Le mot "standard" a plus de sens que juste "web standard" :-) Par exemple:

Ce module aide à garder notre code à un certain standard de qualité.
Ce module assure que les nouveaux contributeurs suivent les standards de style.

Y a-t-il un formateur automatique?

Oui! Vous pouvez utiliser standard --fix pour résoudre la plupart des problèmes automatiquement.

standard --fix fait parti de standard pour un confort maximal. La plupart des problèmes peuvent être résolus, mais quelques erreurs (comme oublier de gérer les erreurs) doivent être résolues manuellement.

Pour gagner du temps, standard produit le message "Run standard --fix to automatically fix some problems" quand il détecte des problèmes qui peuvent être résolus automatiquement.

Comment ignorer des fichiers?

Quelques chemins de fichiers (node_modules/, coverage/, vendor/, *.min.js, bundle.js, et fichiers/dossiers qui commencent avec . comme .git/) sont automatiquement ignorés.

Les chemins de fichiers dans le fichier .gitignore sont aussi automatiquement ignorés.

Parfois, vous devez ignorer d'autres dossiers ou des fichiers spécifiques. Pour cela, ajoutez une propriéte standard.ignore au fichier package.json:

"standard": {
  "ignore": [
    "**/out/",
    "/lib/select2/",
    "/lib/ckeditor/",
    "tmp.js"
  ]
}

Comment cacher certains avertissements?

Dans de rares cas, vous allez devoir enfreindre une règle et cacher l'avertissement généré par standard.

JavaScript Standard Style utilise ESLint et vouz pouvez cacher les avertissements comme vous le feriez avec ESLint.

Désactivez toutes les règles pour une ligne particulière:

file = 'I know what I am doing' // eslint-disable-line

Ou, désactivez seulement la règle "no-use-before-define":

file = 'I know what I am doing' // eslint-disable-line no-use-before-define

Ou, désactivez la règle "no-use-before-define" pour plusieurs lignes:

/* eslint-disable no-use-before-define */
console.log('offending code goes here...')
console.log('offending code goes here...')
console.log('offending code goes here...')
/* eslint-enable no-use-before-define */

J'utilise une bibliothèque logicielle qui pollue l'espace de noms global. Comment puis-je éviter les erreurs "variable is not defined"?

Quelques modules (ex. mocha) mettent leurs fonctions (ex. describe, it) sur l'objet global. Puisque ces fonctions ne sont pas définies ou requises (require'd) nulle part dans votre code, standard vous avertira que vous utilisez une variable qui n'est pas définie (normalement, cette règle est très utile pour capter les fautes d'orthographe!). Mais nous voulons les désactiver pour les variables globales.

Pour informer standard (et les personnes qui lisent votre code) que certaines variables sont globales dans votre code, ajoutez ça au debut de votre fichier:

/* global myVar1, myVar2 */

Si vous avez des centaines de fichiers, il serait peut être désirable d'éviter d'ajouter des commentaires à chaque fichier. Dans ce cas, éxécutez:

$ standard --global myVar1 --global myVar2

Ou, ajoutez ça au fichier package.json:

{
  "standard": {
    "globals": ["myVar1", "myVar2"]
  }
}

Note: global et globals sont équivalents.

Comment puis-je utiliser les fonctionalités expérimentales de JavaScript(ES Next)?

standard supporte les dernières fonctionalités d'ECMAScript, ES8 (ES2017), comprenant les propositions qui sont à l'"étape 4" du processus de proposition.

Pour supporter les fonctionalités expérimentales, standard supporte la spécification d'un parseur JavaScript personalisé. Avant d'utiliser un parseur personalisé, il faut considérer si la compléxité ajoutée vaut le coup.

Pour utiliser un autre parseur, installez-le d'abord avec npm:

npm install @babel/eslint-parser --save-dev

Ensuite éxécutez:

$ standard --parser @babel/eslint-parser

Ou, ajoutez ça au package.json:

{
  "standard": {
    "parser": "@babel/eslint-parser"
  }
}

Si standard est installé globalement (npm install standard --global), soyez surs d'installer @babel/eslint-parser globalement aussi, avec npm install @babel/eslint-parser --global.

Puis-je utiliser une variation du langage JavaScript, comme Flow ou TypeScript?

standard supporte les dernières fonctionalités d'ECMAScript. Cependant, Flow et TypeScript ajoutent une nouvelle syntaxe au langage, alors ils ne sont pas supportés par defaut.

Pour supporter les variations, standard supporte la spécification d'un parseur JavaScript personnalisé en même temps qu'un plugin ESLint pour manager la syntaxe modifiée. Avant d'utiliser une variation, demandez-vous si la complexitée ajoutée vaut le coup.

Flow

Pour utiliser Flow, vous allez devoir éxécuter standard avec @babel/eslint-parser comme parseur et eslint-plugin-flowtype comme plugin.

npm install @babel/eslint-parser eslint-plugin-flowtype --save-dev

Ensuite éxécutez:

$ standard --parser @babel/eslint-parser --plugin flowtype

Ou, ajoutez ça au package.json:

{
  "standard": {
    "parser": "@babel/eslint-parser",
    "plugins": [ "flowtype" ]
  }
}

Note: plugin et plugins sont équivalents.

Si standard est installé globalement (npm install standard --global), soyez sur d'installer @babel/eslint-parser et eslint-plugin-flowtype globalement aussi, avec npm install @babel/eslint-parser eslint-plugin-flowtype --global.

TypeScript

Il existe deux méthodes officiellement prises en charge pour utiliser standard avec des fichiers TypeScript.

ts-standard

Comme standard mais avec des règles spécifiques à TypeScript. Le projet utilise eslint-config-standard-with-typescript pour les règles.

eslint-config-standard-with-typescript

Un fichier de configuration eslint avec des règles JavaScript et TypeScript respectant standard.

Et Mocha, Jasmine, QUnit, etc?

Pour supporter Mocha dans les fichiers de test, ajoutez ça en haut des fichiers de test:

/* eslint-env mocha */

Ou, éxécutez:

$ standard --env mocha

Dans cette commande, mocha peut être jasmine, qunit, phantomjs, etc. Pour voir la liste complète, jetez un coup d'oeil a la documentation d'ESLint specifiant les environements. Pour une liste détaillant quelles globales sont disponibles pour ces environements, jetez un coup d'oeil au module npm globals.

Note: env et envs sont équivalents.

Et les Web Workers?

Ajoutez ça en haut du fichier web worker:

/* eslint-env worker */

Cela indique à standard (et aux personnes lisant le code) que self est une global dans le code du web worker.

Pour les Service workers, ajoutez ça:

/* eslint-env serviceworker */

Quelle est la différence entre les avertissements et les erreurs ?

standard traite toutes les violations de règles comme des erreurs, ce qui veut dire que standard quittera avec un code de sortie non nul (erreur).

Cependant, nous pouvons occasionnellement sortir une nouvelle version majeure de standard qui change des règles qui affecte la majorité des utilisateurs standard (par exemple, la transition de var à let/const). Nous faisons ça seulement quand nous pensons que ça vaut le coup et que la règle peut se fixer automatiquement.

Dans ses situations, nous avons une période de transition, dans laquelle, la règle changé est seulement un "avertissement". Les avertissements ne font pas quitter standard avec un code de sortie non nul (erreur). Toutefois, un message sera affiché dans la console. Durant cette période de transition, l'utilisation de standard --fix va mettre à jour votre code pour que ça soit prêt pour la prochaine mise à jour majeur.

L'approche lente et prudente est ce que nous recherchons avec standard. Nous sommes généralement extrêmement prudents dans l'application de l'utilisation des nouvelles fonctionnalités du langage. Nous voulons que l'utilisation de standard soit légère et amusante, c'est pourquoi nous prenons soin d'apporter des modifications qui pourraient vous gêner. Comme toujours, vous pouvez désactiver une règle à tout moment, si nécessaire.

Puis-je vérifier le code dans les fichiers Markdown ou HTML?

Pour vérifier le code dans les fichiers Markdown, utilisez standard-markdown.

Autrement, il y a des plugins ESLint qui peuvent vérifier le code dans les fichiers Markdown, HTML et plein d'autres genres de fichiers:

Pour verifier le code dans les fichiers Markdown, utilisez un plugin ESLint:

$ npm install eslint-plugin-markdown

Ensuite, pour vérifier le JS à l'interieur des blocs de code, éxécutez:

$ standard --plugin markdown '**/*.md'

Pour verifier le code à l'interieur des fichiers HTML, utilisez un plugin ESLint:

$ npm install eslint-plugin-html

Ensuite, pour vérifier le code JS qui apparait dans les <script>, éxécutez:

$ standard --plugin html '**/*.html'

Il y a-t-il un Git `pre-commit`?

#!/bin/bash

# Assurez-vous que tous les fichiers JavaScript prets à être commis passent les standards de style de code
function xargs-r() {
  # Portable version of "xargs -r". The -r flag is a GNU extension that
  # prevents xargs from running if there are no input files.
  if IFS= read -r -d $'\n' path; then
    echo "$path" | cat - | xargs "$@"
  fi
}
git diff --name-only --cached --relative | grep '\.jsx\?$' | sed 's/[^[:alnum:]]/\\&/g' | xargs-r -E '' -t standard
if [[ $? -ne 0 ]]; then
  echo 'JavaScript Standard Style errors were detected. Aborting commit.'
  exit 1
fi

Comment puis-je produire un resultat coloré et joli?

Le resultat integré est simple et direct, mais si vous aimez les trucs sophistiqués, installez snazzy:

$ npm install snazzy

Et éxécutez:

$ standard | snazzy

Il y a aussi standard-tap, standard-json, standard-reporter, et standard-summary.

Il y a-t-il une API Node.js??

Oui!

`async standard.lintText(text, [opts])`

Lint le texte fourni. Un objet opts peut être fourni:

{
  // unique to lintText
  filename: '',         // path of file containing the text being linted

  // common to lintText and lintFiles
  cwd: '',              // current working directory (default: process.cwd())
  fix: false,           // automatically fix problems
  extensions: [],       // file extensions to lint (has sane defaults)
  globals: [],          // custom global variables to declare
  plugins: [],          // custom eslint plugins
  envs: [],             // custom eslint environment
  parser: '',           // custom js parser (e.g. babel-eslint)
  usePackageJson: true, // use options from nearest package.json?
  useGitIgnore: true    // use file ignore patterns from .gitignore?
}

D'autres options peuvent être utilisées à partir d'un fichier package.json s'il est trouvé dans le dossier courant.

L'objet results aura les propriétes suivantes:

const results = {
  results: [
    {
      filePath: '',
      messages: [
        { ruleId: '', message: '', line: 0, column: 0 }
      ],
      errorCount: 0,
      warningCount: 0,
      output: '' // fixed source code (only present with {fix: true} option)
    }
  ],
  errorCount: 0,
  warningCount: 0
}

`async standard.lintFiles(files, [opts], callback)`

Lint les fichiers qui correspondent aux globs fournis. Un objet opts peut être fourni:

{
  // unique to lintFiles
  ignore: [],           // file globs to ignore (has sane defaults)

  // common to lintText and lintFiles
  cwd: '',              // current working directory (default: process.cwd())
  fix: false,           // automatically fix problems
  extensions: [],       // file extensions to lint (has sane defaults)
  globals: [],          // custom global variables to declare
  plugins: [],          // custom eslint plugins
  envs: [],             // custom eslint environment
  parser: '',           // custom js parser (e.g. babel-eslint)
  usePackageJson: true, // use options from nearest package.json?
  useGitIgnore: true    // use file ignore patterns from .gitignore?
}

Objet results (comme au-dessus).

Comment puis-je contribuer a `standard`?

Les contributions sont bienvenues! Jetez un coup d'oeil aux issues et aux PRs, et faites la votre si vous voulez quelque chose que vous ne trouvez pas la.

Envie de discuter? Joignez les contributeurs sur IRC dans la chaine #standard sur freenode.

Voici quelques modules importants dans l'ecosystème standard:

standard - ce repo
- standard-engine - le moteur cli pour les règles eslint
- eslint-config-standard - les règles eslint pour standard
- eslint-config-standard-jsx - les règles eslint pour standard (JSX)
- eslint-plugin-standard - règles eslint customisées pour standard (ne fait pas partie de eslint core)
- eslint - le linteur qui alimente standard
snazzy - résultats de standard plus jolis dans le terminal
standard-www - le code pour https://standardjs.com
semistandard - standard, avec point-virgules (si nécessaire)

Il y a aussi plein de plugins pour editeur, une liste de modules npm qui utilisent standard, et une super liste de modules dans l'ecosystème standard.