JavaScript Standard Style

As Regras

2 espaços – para identação
Aspas simples para strings – exceto para evitar escapamentos
Sem variáveis não-utilizadas – resolve uma porrada de bugs!
Sem ponto-e-vírgulas – Dá boa. Sério!
Nunca comece uma linha com (, [, ou `
- Esse é o único problema em omitir ponto-e-vírgula – checado automaticamente pra você!
- Mais detalhes
Espaço após keywords if (condição) { ... }
Espaço antes dos nomes das funções function nome (arg) { ... }
Sempre use === ao invés de == – mas obj == null é permitido para checar se null || undefined.
Sempre lide com o parâmetro err do node.
Sempre prefixe globais de browser com window – exceto document e navigator, essas tudo bem.
- Previne o uso acidental de globais de browser mal-nomeadas como open, length, event, e name.
E mais benefícios – dê uma chance para standard hoje!

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.

Índice

Instalação
Uso
FAQ
Node.js API
- standard.lintText(text, [opts], callback)
- standard.lintFiles(files, [opts], callback)
Licensa

Instalação

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.

Uso

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.

O que você pode fazer se for espertinho

Adicione isso ao package.json

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

Cheque os estilos manualmente quando rodar npm test

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

Nunca dê feedback de estilo num pull request de novo!

Insígnia

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/standard/standard/master/badge.svg)](https://github.com/standard/standard)

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

Plugins de Editores de Texto

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.

FAQ

Por que eu deveria usar o JavaScript 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:

Zero configuração. A forma mais fácil de forçar consistência de estilo no seu projeto. É só tacar lá e pronto.
Captura erros de estilo antes de serem enviados em PR's. Salva um tempo precioso de code review eliminando vai-e-vem entre mantenedor e contribuínte.

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 open source pode ser um lugar hostil para novatos. Deixar as expectativas do contribuínte claras e automatizadas deixa o projeto mais saudável.

Discordo da regra X, você pode mudá-la?

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.

Mas isso não é um padrão legítimo!

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 standard/standard e não ECMA/standard.

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

Esse módulo ajuda a manter seu código num alto padrão de qualidade.
Esse módulo assegura que novos contribuíntes sigam alguns padrões de estilo básicos.

Existe um formatador automático?

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

Como ignoro arquivos?

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"
  ]
}

Como escondo um determinado aviso?

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 em 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 */

Eu uso uma biblioteca que polui o namespace global. Como eu previno erros de "variable is not defined"?

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 arquivos, adicionar comentários em cada um pode ficar um saco; Nesses casos, você pode adicionar isso ao package.json:

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

Posso usar um custom parser de JS novinho em folha que saiu ontem para suporte ao ES Next?

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.

Posso usar uma linguagem variante de JavaScript, tipo Flow?

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.

Você pode tornar regra X configurável?

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

E os Web Workers?

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.

E a respeito de Mocha, Jasmine, QUnit, etc?

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 .

Existe um hook `pre-commit` para Git?

Curioso você perguntar!

#!/bin/bash

# Ensure all javascript files staged for commit pass standard code style
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

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

Como eu deixo o output todo coloridinho e bonitinho?

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.

Node.js API

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

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
}

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

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

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 encontrou aqui.

Junte-se ao #standard no freenode.

Quero contribuir com o `standard`. Quais packages eu devo conhecer?

standard - esse repo
- standard-engine - Motor cli para regras arbitrárias de ESLint
- eslint-config-standard - Regras ESLint para standard
- eslint-plugin-standard - Regras ESLint custom para standard (Não fazem parte do core do ESLint)
- eslint - O linter que move o standard
standard-format - Formatador de código automático
snazzy - Output de terminal bonitinho
standard-www - código do https://standardjs.com
semistandard - standard, com ponto-e-vírgula (se você precisar)

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

License

MIT. Copyright (c) Feross Aboukhadijeh.

Files

README-ptbr.md

Latest commit

History