JavaScript Standard Style

Um Guia de Estilo JavaScript para a todos governar

Translations: English, Spanish, 繁體中文, 简体中文


Sem ter que tomar decisões; Sem gerenciar .eslintrc, .jshintrc, ou .jscsrc . Funciona logo de cara.

Esse módulo salva o seu tempo (e de outras pessoas!) de duas formas:

Instale:

npm install standard

Para ter uma idéia melhor, dê uma olhada num arquivo amostra escrito no JavaScript Standard Style, ou dê uma olhada em alguns dos repositórios que usam standard.

A forma mais fácil de usar o JavaScript Standard Style para checar seu código é instalá-lo globalmente como se fosse um programa de linha de comando do Node. Para isso, simplesmente execute o seguinte comando no seu terminal (a flag -g instala o standard globalmente no seu sistema, omita-a se quiser instalar no seu diretório de trabalho atual.)

npm install standard --global

Ou você pode rodar este comando para instalar standard localmente, para usar no seu módulo:

npm install standard --save-dev

Node.js e npm são requisitos para rodar este programa.

Depois de você ter instalado standard, você será capaz de usá-lo. O caso de uso mais simples seria checar o estilo de todos os arquivos JavaScript no diretório de trabalho atual:

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

Você pode passar opcionalmente um diretório (ou diretórios) usando o padrões glob. Assegure-se de colocar aspas nos caminhos contendo padrões glob para que eles sejam expandidos pelo standard ao invés da sua shell.

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

Note: por padrão standard vai procurar por todos os arquivos que casarem com os padrões:: **/*.js, **/*.jsx.

  1. Adicione isso ao package.json
{
  "name": "meu-package-legalzao",
  "devDependencies": {
    "standard": "*"
  },
  "scripts": {
    "test": "standard && node my-tests.js"
  }
}
  1. Cheque os estilos manualmente quando rodar npm test
$ npm test
Error: Use JavaScript Standard Style
  lib/torrent.js:950:11: Expected '===' and instead saw '=='.
  1. Nunca dê feedback de estilo num pull request de novo!

Está usando em um dos seus projetos? Inclua uma dessas insígnias no seu readme para que as pessoas saibam que seu código está em standard style.

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

[![Standard - JavaScript Style Guide](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](https://standardjs.com/)

Primeiro, instale standard. Então, instale o plugin apropriado para o seu editor.

Sublime Text

Usando Package Control, instale SublimeLinter e SublimeLinter-contrib-standard.

Para formatação automática ao salvar, instale StandardFormat.

Atom

Instale linter-js-standard.

Para formatação automática, instale standard-formatter. Para snippets, installe standardjs-snippets.

Vim

Instale Syntastic e adicione essa linha ao seu .vimrc:

let g:syntastic_javascript_checkers = ['standard']

Para formatação automática ao salvar, instale standard-format

npm install -g standard-format

e adicione essas duas linhas ao seu .vimrc:

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

Emacs

Instale Flycheck e cheque o manual para aprender a habilitar nos seus projetos.

Brackets

Selecione o registro da extensão do "Standard Code Style".

Visual Studio Code

Instale vscode-standardjs. (Inclui suporte para formatação automática.)

Para snippets de React, instale vscode-react-standard.

WebStorm/PhpStorm

Ambos PhpStorm e WebStorm podem ser configurados para Standard Style.

A beleza do JavaScript Standard Style reside no fato de ser simples. Ninguém quer manter vários arquivos de centenas de linhas de configuração de estilo para cada módulo/projeto em que trabalham. Chega dessa patifaria!

Esse módulo te faz economizar tempo de 2 formas:

Adotar o estilo standard significa elevar a importância da clareza de código e convenções de comunidade a um patamar acima do estilo pessoal. Pode não fazer sentido para TODOS os projetos e culturas de desenvolvimento, porém, o opens ource pode ser um lugar hostil para novatos. Deixar as expectativas do contribuínte claras e automatizadas deixa o projeto mais saudável.

Não. O ponto principal do standard é evitar bikeshedding sobre estilos. Há vários debates online sobre tabs vs. espaços, etc., que nunca vão terminar. Esses debates apenas tiram as pessoas do foco, que deveria ser terminar seus projetos. No fim das contas você só tem que 'escolher um', e essa é a filosofia do standard - um monte de opiniões 'escolha um' juntadas com todo o cuidado. Espero que os usuários percebam o valor nisso ao invés de defender suas próprias opiniões.

Claro que não! O estilo aqui disposto não é afiliado com nenhum grupo de padrões web oficiais, e é por isso que esse repo se chama feross/standard e não ECMA/standard.

A palavra "standard" tem muito mais significado do que só "web standard" :-) Por exemplo:

Sim! Você pode usar standard --fix para consertar a maioria dos problemas automaticamente.

standard --fix vem junto do standard (since v8.0.0) para conveniência máxima. Há muitos problemas corrigíveis, mas alguns erros, tipo não tratar erros nos callbacks do node, devem ser corrigidos manualmente.

Para economizar seu tempo, standard solta uma mensagem ("Run standard --fix to automatically fix some problems.") quando detecta problemas que podem ser corrigidos manualmente.

Alternativamente, se seu código é feito apenas de ES5, você pode tentar usar standard-format (um pacote separado), mas provavlemente não vai ser mantido pois standard --fix funciona muito bem, e isso faz com que não precisemos manter duas ferramentas com regras de configuração separadas.

Os caminhos node_modules/**, *.min.js, bundle.js, coverage/**, pastas/arquivos escondidos (começando com .), e todos os arquivos nos padrões no .gitignore da raiz do projeto são automaticamente ignorados.

Às vezes você precisa ignorar algumas pastas adicionais ou arquivos minificados específicos. Para fazer isso, adicione uma propriedade standard.ignore no package.json:

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

Em casos raros, você vai precisar quebrar uma regra e esconder um warning gerado pelo standard.

JavaScript Standard Style usa o eslint por baixo dos panos, sendo assim, você pode esconder algum aviso da mesma forma que você faria se utilizasse eslint diretamente.

Para receber output verboso (para que você descubra que regra em particular precisa ignorar), execute:

$ standard --verbose
Error: Use JavaScript Standard Style
  routes/error.js:20:36: 'file' was used before it was defined. (no-use-before-define)

Desabilite todas as regras oem uma linha específica:

file = 'Eu sei bem o que tô fazendo' // eslint-disable-line 

Ou, desabilite apenas na regra "no-use-before-define":

file = 'Eu sei bem o que tô fazendo' // eslint-disable-line no-use-before-define 

Ou, desabilite a regra "no-use-before-define" em várias linhas:

/* eslint-disable no-use-before-define */
console.log('código fora do padrão...')
console.log('código fora do padrão...')
console.log('código fora do padrão...')
/* eslint-enable no-use-before-define */

Alguns packages (tipo o mocha) colocam suas funções (tipo describe, it) no objeto global (que ruim!). Devido ao fato dessas funções não serem definidas ou chamadas via require em lugar algum do seu código, standard vai te avisar que você tá usando uma variável que não está definida (geralmente essa regra é bastante útil para pegar typos!). Mas queremos desabilitar essa função para variáveis globais.

Para fazer com que o standard (e outros humanos que lerão seu código) saibam que algumas variáveis são globais no seu código, adicione isso ao topo do seu arquivo:

/* global myVar1, myVar2 */

Se você possui centenas de arquivps, adicionar comentários em cada um pode ficar um saco; Nesses casos, você pode adicionar isso ao package.json:

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

Antes de usar um custom parser, considere se a complexidade a mais no seu código faz com que o processo valha a pena.

standard suporta custom JS parsers. Para usar um custom parser, instale via npm (por exemplo: npm install babel-eslint) e adicione isso ao seu package.json:

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

Se você está usando standard de forma global (instalou com -g), você vai precisar instalar babel-eslint globalmente como npm install babel-eslint -g.

Antes de usar uma variante de JS customizada, considere se a complexidade a mais no seu processo de construção (e os esforços necessários para conseguir contribuíntes numa velocidade boa) valem a pena.

standard suporta plugins de ESLint. Use um desses para transformar seu código em JavaScript válido antes que standard o veja. Para usar um custom parser, instale via npm (exemplo: npm install eslint-plugin-flowtype) e adicione isso ao seu package.json:

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

Se você está usando standard globalmente (instalou com -g), você também terá que instalar eslint-plugin-flowtype globalmente com npm install eslint-plugin-flowtype -g.

Não. O objetivo do standard é economizar seu tempo escolhendo regras razoáveis para que você gaste seu tempo resolvendo problemas de verdade. Se você realmente quer configurar centenas de regras ESLint individualmente, você sempre pode usar eslint diretamente.

Se você apenas quer trocar algumas regras, considere usar essa configuração compartilhável e jogue suas mudanças em cima.

Dica: Use standard e pronto. Há problemas reais que você poderia usar seu tempo resolvendo! :P

Adicione isso no topo do seu arquivo:

/* eslint-env serviceworker */

Isso permite que standard (e outras pessoas que lerão seu código) saibam que self é uma global num código de web worker.

Para ter suporte a mocha nos seus arquivos de teste, adicione isso no começo do seus arquivos de teste:

/* eslint-env mocha */

Onde mocha pode ser jasmine, qunit, phantomjs, e por aí vai. Para ver a lista completa, cheque a documentação para especificar ambientes do ESLint. Para uma lista de quais variávies globais estão disponíveis nesses ambientes, cheque o módulo npm globals .

Curioso você perguntar!

#!/bin/sh 
# Ensure all javascript files staged for commit pass standard code style 
git diff --name-only --cached --relative | grep '\.jsx\?$' | xargs standard
if [ $? -ne 0 ]; then exit 1; fi

Alternativamente, overcommit é um gerenciador de ganchos Git que incluem suporte para rodar standard como um gancho pre-commit de Git. Para habilitar, adicione o seguinte ao seu .overcommit.yml:

PreCommit:
  Standard:
    enabled: true

O output de fábrica é simples e direto, mas se você gosta de coisinhas brilhantes, instale snazzy:

npm install snazzy

E rode:

$ standard --verbose | snazzy

Há também standard-tap, standard-json, standard-reporter, e standard-summary.

Aplica lint no código fornecido text para forçar JavaScript Standard Style. Um objeto opts pode ser fornecido:

var opts = {
  fix: false,   // automaticamente corrige problemas 
  globals: [],  // declaração de variáveis globais 
  plugins: [],  // plugins eslint 
  envs: [],     // ambiente eslint 
  parser: ''    // js parser (e.g. babel-eslint) 
}

O callback vai ser chamado com os objetos Error e results:

var results = {
  results: [
    {
      filePath: '',
      messages: [
        { ruleId: '', message: '', line: 0, column: 0 }
      ],
      errorCount: 0,
      warningCount: 0
    }
  ],
  errorCount: 0,
  warningCount: 0
}

Aplica lint nos globs files. Um objeto opts pode ser passado

var opts = {
  ignore: [],   // globs de arquivo para ser ignorados (has sane defaults) 
  cwd: '',      // diretório atual de trabalho (default: process.cwd()) 
  fix: false,   // corrige problemas automaticamente 
  globals: [],  // variáveis globais para declarar 
  plugins: [],  // plugins eslint 
  envs: [],     // ambiente eslint 
  parser: ''    // js parser (e.g. babel-eslint) 
}

O callback vai ser chamado com os objetos Error e results:

Contribuições são bem-vindas! Cheque o issues ou os PRs, e faça o seu próprio se quiser algo que não encontra aqui.

Junte-se ao #standard no freenode.

Há vários plugins de editores, uma lista de packages que usam standard, e uma awesome list de packages do ecossistema standard .

MIT. Copyright (c) Feross Aboukhadijeh.