Se um projeto precisar de um formatador de código diferente, defina a escolha no nível do projeto: use o arquivo de configuração desse projeto e, se você trabalha no Visual Studio Code, suas configurações de workspace. Isso mantém seus padrões de usuário do VS Code intactos, ao mesmo tempo em que torna a escolha de formatação do projeto reproduzível. As etapas abaixo têm como foco o macOS e o VS Code; outros editores podem usar controles diferentes.

Decida o que “formatador” significa para este projeto

Primeiro, identifique a linguagem e a necessidade real. Um formatador reescreve o código para um estilo; uma configuração básica do editor pode controlar apenas indentação, finais de linha ou espaços em branco. Por exemplo, o EditorConfig fornece propriedades de estilo de projeto que os editores compatíveis podem ler, enquanto o Prettier é um formatador com sua própria configuração de projeto. Essas ferramentas podem se complementar, mas um arquivo EditorConfig por si só não seleciona nem instala um formatador. O EditorConfig descreve seu formato e plugins de editor; o guia de configuração do Prettier explica como ele lê os arquivos de configuração compatíveis.

Verifique qual formatador já é usado pelo projeto antes de adicionar outro. Olhe o manifesto de pacotes, a configuração do formatador e a documentação do projeto. Se colegas de equipe ou verificações automatizadas esperam uma ferramenta ou versão específica, corresponder a essa configuração geralmente é a escolha mais prática. Instalar um formatador concorrente ou alterar suas opções pode produzir diffs grandes, mesmo quando o código continua funcionando.

Escolha onde a configuração deve ficar

No VS Code, as configurações do usuário se aplicam a todo o seu uso do editor, enquanto as configurações de workspace se aplicam ao projeto aberto e têm precedência sobre as configurações do usuário. O VS Code mantém as configurações de workspace em uma pasta .vscode na raiz do projeto; as configurações do usuário são armazenadas separadamente no diretório Application Support da sua conta macOS. Use a Command Palette (⇧⌘P) e escolha Preferences: Open Workspace Settings (JSON) para editar a configuração do projeto. Confirme que o editor de configurações exibe Workspace antes de alterar qualquer coisa. A documentação de configurações do VS Code explica os escopos e locais.

Para escolher um formatador apenas para uma linguagem neste projeto, adicione uma entrada de formatador padrão específica para a linguagem nas configurações de workspace. Por exemplo, se o projeto usa a extensão do Prettier para VS Code em JavaScript, a configuração tem este formato:

{
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

Use o identificador de extensão referente ao formatador realmente instalado no seu editor; o exemplo não é um identificador universal. Se o projeto incluir várias linguagens, adicione uma entrada para cada linguagem relevante em vez de definir um padrão global. O comando Format Document With... do VS Code permite que você escolha entre os formatadores disponíveis para o documento atual, e suas ações de formatação podem ser invocadas a partir da Command Palette. O guia de formatação do VS Code documenta esses controles. Evite ativar a formatação ao salvar como parte dessa alteração pontual, a menos que queira que cada salvamento nesse projeto acione a formatação.

Mantenha as regras do formatador com o projeto

Um formatador padrão seleciona uma ferramenta; ele não define todas as regras de formatação dessa ferramenta. Armazene as regras compartilhadas em um arquivo de configuração que o formatador escolhido reconheça. Para o Prettier, isso poderia ser um arquivo .prettierrc.json na raiz do projeto. Um exemplo mínimo pode especificar apenas as opções que o projeto combinou em utilizar:

{
  "singleQuote": true
}

O Prettier busca a configuração a partir do arquivo que está sendo formatado até seus diretórios pai, portanto, uma configuração no nível raiz pode atender aos arquivos abaixo dela. Ele também oferece suporte a vários outros formatos de configuração; escolha um compatível com a versão do projeto e com as ferramentas existentes. A documentação de configuração do Prettier lista os arquivos suportados e o comportamento de resolução.

Se o objetivo for apenas indentação consistente ou finais de linha padronizados entre editores, considere usar um .editorconfig na raiz. Por exemplo, root = true interrompe a busca por arquivos EditorConfig mais distantes, e propriedades como indent_style, indent_size e end_of_line podem definir convenções básicas de texto. O suporte do editor varia de acordo com o plugin, e essas propriedades não substituem as regras de formatação com reconhecimento de linguagem. A especificação e visão geral do EditorConfig descrevem como os arquivos são encontrados e como as regras correspondentes são aplicadas.

Verifique o escopo antes de formatar

Salve a configuração de workspace e o arquivo de configuração e, se necessário, reabra a pasta do projeto no VS Code. Abra um arquivo representativo e use Format Document With... para confirmar o formatador selecionado. Se o formatador não estiver listado, verifique se a extensão correspondente está instalada e se suporta essa linguagem; uma configuração de workspace não pode instalar uma extensão nem adicionar suporte a formatadores por conta própria.

Antes de aplicar a formatação de forma ampla, inspecione os arquivos afetados no Controle de Versão (Source Control) ou em uma visualização de diff. Formate primeiro um pequeno conjunto representativo, especialmente se o projeto tiver regras de estilo existentes ou arquivos gerados. Se o resultado for inesperado, pare e verifique se há uma configuração concorrente em um diretório pai, uma configuração específica para a linguagem ou outro formatador que o projeto já espera. Reverta uma alteração de formatação indesejada por meio das ferramentas de controle de versão do editor, depois ajuste a configuração do projeto e repita o processo em um conjunto pequeno.

Isso mantém a decisão vinculada ao projeto: os padrões de usuário do VS Code permanecem em seu escopo separado, enquanto o projeto pode carregar sua própria seleção de formatador e regras. Se você trocar de editor, a configuração de workspace não o acompanhará, portanto, confie na configuração de projeto do formatador quando esse editor oferecer suporte a ela.

Fontes