clang-format (configuração)

Configuração do clang-format

Configure a ferramenta de formatação de código clang-format usando modelos prontos para uso, scripts de integração e documentação de referência abrangente.

Propósito

Esta skill fornece fluxos de trabalho procedimentais para tarefas de configuração do clang-format:

• Criar novos arquivos .clang-format a partir de modelos testados
• Analisar o estilo de código existente e gerar configurações correspondentes
• Configurar a integração com editores e Git usando scripts fornecidos
• Depurar o comportamento da formatação com a ajuda da documentação de referência

Roteamento de Fluxo de Trabalho por Tipo de Acionador

Uma vez invocada, direcione para o fluxo de trabalho apropriado com base em qual acionador foi ativado:

Acionador 1: Menção explícita ao clang-format → Se o usuário perguntar sobre opções específicas: Consulte references/01-09.md para a categoria relevante → Se o usuário precisar de uma referência completa: Direcione para references/complete/clang-format-style-options.md → Se o usuário perguntar sobre o uso da CLI: Consulte references/cli-usage.md

Acionador 2: Solicitação de análise de estilo de código → Siga o fluxo de trabalho "Analisando Estilo de Código Existente" abaixo → Examine amostras de código sistematicamente (chaves → indentação → espaçamento → quebra de linha → alinhamento) → Mapeie os padrões para o modelo mais próximo em assets/configs/ → Gere uma hipótese de configuração inicial como um arquivo de configuração temporário "/tmp/<nome_do_repo>/hipotese_.clang-format" → VERIFIQUE O IMPACTO: Execute clang-format --style="/tmp/<nome_do_repo>/hipotese_<numero>.clang-format" arquivo.cpp | diff - arquivo.cpp em 3 a 5 amostras representativas → MEÇA O IMPACTO usando pontuação ponderada: • Métrica 1: Alterações na contagem de linhas (linhas adicionadas/removidas) - peso 10 • Métrica 2: Alterações de espaços em branco dentro da linha (espaçamento dentro de linhas existentes) - peso 1 • Pontuação de Impacto = (alterações_linhas × 10) + (alterações_espacos × 1) • Pontuação mais baixa = menor impacto em conflitos de rebase, futuras análises de git-diff e revisões de merge request = melhor configuração → ITERE: Ajuste as opções de configuração visando as configurações de maior impacto, reteste, compare as pontuações → REPITA até atingir a pontuação mínima possível, mantendo a aplicação consistente do estilo → RELATE AO USUÁRIO: Apresente a configuração vencedora com: • Pontuação de impacto final e detalhamento (alterações de linha vs. alterações de espaços em branco) • Tabela de comparação mostrando todas as hipóteses testadas e suas pontuações • Exemplos de snippets diff mostrando o que mudará, com comandos para o usuário testar por conta própria em arquivos de sua escolha. • Justificativa para a configuração selecionada → AGUARDE A APROVAÇÃO DO USUÁRIO antes de finalizar a configuração → Somente após a aprovação: forneça o arquivo de configuração final

Acionador 3: Operações com arquivos de configuração → Se for criar um novo: Siga o fluxo de trabalho "Criando Nova Configuração a partir de Modelo" → Se for modificar um existente: Leia a configuração atual, identifique as alterações necessárias, consulte o guia de categoria relevante → Se for gerar a partir de código: Use o fluxo de trabalho do Acionador 2 (análise de estilo de código)

Acionador 4: Investigação de comportamento de formatação → Siga o fluxo de trabalho "Depurando Problemas de Formatação" abaixo → Verifique a detecção da configuração com --dump-config → Identifique a categoria afetada, consulte o guia references/0X.md relevante → Teste opções isoladas com uma configuração mínima

Acionador 5: Consultas sobre opções de estilo → Mapeie a pergunta para a categoria: chaves→03, indentação→04, espaçamento→05, alinhamento→01, quebra de linha→02 → Consulte o guia de categoria específico em references/ → Forneça exemplos de quick-reference.md, se aplicável

Acionador 6: Solicitações de alteração com impacto mínimo → Use o fluxo de trabalho "Analisando Estilo de Código Existente" para corresponder aos padrões atuais → Enfatize começar pelo modelo mais próximo para minimizar alterações → Teste em amostras representativas antes da aplicação em todo o projeto → Documente quais padrões foram preservados vs. normalizados

Recursos Inclusos

Modelos de Configuração (assets/configs/)

Sete modelos .clang-format prontos para uso, otimizados para cenários comuns:

• google-cpp-modified.clang-format - Estilo Google C++ com indentação de 4 espaços, limite de 120 colunas
• linux-kernel.clang-format - Padrões de codificação do kernel Linux (tabs, chaves K&R)
• microsoft-visual-studio.clang-format - Convenções Microsoft/Visual Studio
• modern-cpp17-20.clang-format - Estilo moderno C++17/20 com expressões contemporâneas
• compact-dense.clang-format - Estilo compacto para ambientes com restrição de espaço
• readable-spacious.clang-format - Estilo espaçoso priorizando a legibilidade
• multi-language.clang-format - Configuração multilinguagem (C++, JavaScript, Java)

Quando usar modelos: Iniciar novos projetos, estabelecer padrões de equipe ou testar rapidamente abordagens de formatação.

Scripts de Integração (assets/integrations/)

Três scripts de integração com editores e Git:

• pre-commit - Script de hook Git para formatação automática de arquivos preparados (funciona com os frameworks pre-commit ou prek)
• vimrc-clang-format.vim - Configuração do Vim para formatar ao salvar
• emacs-clang-format.el - Configuração do Emacs para integração com clang-format

Quando usar integrações: Configurar formatação automática no fluxo de trabalho de desenvolvimento.

Nota: O script de hook pre-commit funciona tanto com o framework pre-commit (Python) quanto com o prek (alternativa em Rust). Ambos os frameworks usam .pre-commit-config.yaml com sintaxe idêntica.

Documentação de Referência (references/)

Documentação detalhada organizada por categoria:

Navegação Rápida:

• index.md - Visão geral e hub de documentação
• quick-reference.md - Configurações funcionais completas com explicações
• cli-usage.md - Uso da linha de comando, configuração de editores, integração CI/CD

Categorias de Opções (01-09.md):

1. 01-alignment.md - Alinhamento vertical de declarações, atribuições, operadores
2. 02-breaking.md - Regras de quebra de linha e encapsulamento
3. 03-braces.md - Estilos de posicionamento de chaves (K&R, Allman, GNU, etc.)
4. 04-indentation.md - Regras de indentação e casos especiais
5. 05-spacing.md - Controle de espaços em branco ao redor de operadores, palavras-chave
6. 06-includes.md - Organização e ordenação de includes/imports
7. 07-languages.md - Opções específicas de linguagem para C++, Java, JavaScript
8. 08-comments.md - Formatação e reflow de comentários
9. 09-advanced.md - Sistema de penalidades, formatação de strings literais, recursos experimentais

Referência Completa (complete/):

• clang-format-cli.md - Documentação completa da interface de linha de comando
• clang-format-style-options.md - Todas as 194 opções de estilo com exemplos

Fluxos de Trabalho Comuns

Criando Nova Configuração a partir de Modelo

Para criar um novo arquivo .clang-format:

1. Identifique os requisitos (guia de estilo, preferências da equipe, linguagem)
2. Selecione o modelo mais próximo em assets/configs/
3. Copie o modelo para a raiz do projeto como .clang-format
4. Teste a formatação: clang-format --dry-run arquivo.cpp
5. Personalize opções específicas usando references/01-09.md conforme necessário
6. Verifique as alterações: clang-format arquivo.cpp | diff - arquivo.cpp

Exemplo:

# Copiar modelo Google C++
cp assets/configs/google-cpp-modified.clang-format /caminho/para/projeto/.clang-format

# Testar em arquivo de exemplo
clang-format --dry-run /caminho/para/projeto/src/main.cpp

# Aplicar se satisfatório
clang-format -i /caminho/para/projeto/src/*.cpp

Analisando Estilo de Código Existente

Para gerar uma configuração que corresponda ao código existente:

1. Examine amostras de código em busca de padrões de formatação
2. Identifique as principais características:
   • Posicionamento de chaves → consulte references/03-braces.md
   • Indentação (espaços/tabs, largura) → consulte references/04-indentation.md
   • Espaçamento (operadores, palavras-chave) → consulte references/05-spacing.md
   • Quebra de linha (limite de coluna, encapsulamento) → consulte references/02-breaking.md
   • Padrões de alinhamento → consulte references/01-alignment.md
3. Mapeie os padrões para o estilo base mais próximo em references/quick-reference.md
4. Comece com esse modelo de assets/configs/
5. Substitua opções específicas para corresponder aos padrões observados
6. Teste em amostras de código representativas
7. Itere até que a formatação corresponda ao estilo existente

Este fluxo de trabalho minimiza alterações exclusivamente de espaços em branco ao introduzir o clang-format em projetos existentes.

Configurando Integração com Editor

Para habilitar a formatação ao salvar em editores:

Vim:

1. Copie o conteúdo de assets/integrations/vimrc-clang-format.vim para .vimrc
2. Reinicie o Vim ou execute source na configuração
3. Salve qualquer arquivo C/C++/Java para acionar a formatação

Emacs:

1. Copie assets/integrations/emacs-clang-format.el para a configuração do Emacs
2. Reinicie o Emacs ou avalie a configuração
3. Salve qualquer arquivo suportado para acionar a formatação

Outros editores: Consulte references/cli-usage.md para instruções de configuração do VS Code, CLion e outros editores.

Configurando Hook Git para Formatação

Opção 1: Usando o framework pre-commit/prek (Recomendado) :

Configure em .pre-commit-config.yaml:

repos:
  - repo: https://github.com/pre-commit/mirrors-clang-format
    rev: v19.1.7
    hooks:
      - id: clang-format

Em seguida, instale: pre-commit install ou prek install

Opção 2: Hook Git manual :

1. Copie assets/integrations/pre-commit para .git/hooks/pre-commit
2. Torne executável: chmod +x .git/hooks/pre-commit
3. Teste preparando (staging) e commitando alterações

O hook formata apenas os arquivos preparados, preservando as alterações não preparadas.

Depurando Problemas de Formatação

Quando a formatação produz resultados inesperados:

1. Verifique a detecção da configuração: clang-format --dump-config arquivo.cpp
2. Verifique as opções de comando em references/cli-usage.md
3. Identifique a categoria de formatação afetada (chaves, espaçamento, quebra de linha, etc.)
4. Consulte o guia de categoria relevante em references/01-09.md
5. Teste opções isoladas: crie uma configuração mínima com a opção suspeita
6. Para detalhes abrangentes sobre opções, consulte references/complete/clang-format-style-options.md

Configurando Verificações de Formatação em CI/CD

Para aplicar a formatação na integração contínua:

1. Revise os exemplos de CI em references/cli-usage.md
2. Adicione a verificação clang-format ao pipeline:

   # Verificar formatação sem modificar arquivos
   clang-format --dry-run --Werror src/**/*.{cpp,h}
   

3. Configure para falhar a build em violações de formatação
4. Documente os requisitos de formatação para contribuidores

Conceitos Chave

Estilos Base: Configurações predefinidas (LLVM, Google, Chromium, Mozilla, WebKit, Microsoft, GNU) fornecem pontos de partida. Defina com BasedOnStyle: Google e depois substitua opções específicas.

Suporte a Múltiplas Linguagens: Configure diferentes linguagens separadamente em um único arquivo usando a chave Language:. Veja assets/configs/multi-language.clang-format para um exemplo.

Sistema de Penalidades: O clang-format usa penalidades para escolher entre alternativas de formatação. Valores de penalidade mais altos desencorajam escolhas específicas. Consulte references/09-advanced.md para detalhes.

Refinamento Progressivo: Comece com o modelo mais próximo dos requisitos e depois personalize incrementalmente. Teste frequentemente em amostras de código representativas.

Testando Configurações

# Visualizar alterações sem modificar o arquivo
clang-format --dry-run arquivo.cpp

# Mostrar diff das alterações propostas
clang-format arquivo.cpp | diff - arquivo.cpp

# Aplicar formatação ao arquivo
clang-format -i arquivo.cpp

# Formatar o projeto inteiro
find src include -name '*.cpp' -o -name '*.h' | xargs clang-format -i

# Verificar formatação em CI (falhar em violações)
clang-format --dry-run --Werror src/**/*.{cpp,h}

Estratégia de Navegação

Para a maioria das tarefas, siga esta progressão:

1. Comece com modelos: Navegue por assets/configs/ para configurações prontas para uso
2. Referência rápida: Verifique references/quick-reference.md para configurações completas com explicações
3. Guias de categoria: Consulte references/01-09.md para categorias de opções específicas
4. Uso da CLI: Consulte references/cli-usage.md para detalhes de linha de comando e integração
5. Referência completa: Use references/complete/ para documentação exaustiva de opções

Ao analisar código ou depurar problemas, identifique o aspecto de formatação (chaves, espaçamento, alinhamento, etc.) e vá diretamente para o guia de categoria relevante em references/.