Desenvolvi um formatador de C, C++, Java e JavaScript com Clang para o ambiente Node.js.
(github.com/lumirlumir)- Repositório no GitHub: https://github.com/lumirlumir/npm-clang-format-node
- Site da documentação oficial: https://clang-format-node.lumir.page/
Olá!
Desenvolvi um formatador de C, C++, Java e JavaScript que utiliza o Clang no ambiente Node.js. Este projeto foi iniciado do zero com base no pacote clang-format do Angular, que não recebe mais manutenção.
Compartilhei algo parecido há dois ou três meses, e agora, com o lançamento da versão v1.3.0, adicionei um site de documentação detalhado para que os usuários possam usar a ferramenta com mais facilidade e conveniência. O site de documentação pode ser acessado aqui e inclui desde o método básico de instalação até os motivos para usar este pacote, então acho que pode ser útil para quem tiver interesse.
Nesta atualização, adicionei vários testes para aumentar ainda mais a estabilidade do pacote, e novos recursos também foram incluídos.
Todo o pacote está sob a licença MIT e pode ser usado livremente.
O que é o projeto clang-format-node?
Este pacote é um pacote Node.js baseado no clang-format do Clang, famoso compilador C da LLVM, e oferece suporte à formatação de código nas linguagens C, C++, Java. Em resumo, ele cumpre um papel semelhante ao do Prettier no ambiente Node.js, mas se diferencia por oferecer formatação para C, C++ e Java, linguagens que o Prettier não suporta.
Em especial, o clang-format-node é útil em casos como desenvolvimento do core do Node.js ou de aplicações Electron, em que é preciso escrever código JavaScript junto com código C/C++.
O pacote clang-format existente tinha a inconveniência de exigir a instalação de dependências adicionais dependentes do sistema operacional, como Ubuntu, mas com este pacote é possível usar tudo imediatamente, sem instalação separada. Além disso, enquanto o pacote anterior tinha aspectos que dificultavam a integração em fluxos de trabalho de CI baseados em Node.js e npm, o clang-format-node pode ser usado facilmente apenas instalando via npm e configurando um script, o que traz muitas vantagens em ambientes de CI.
Então, quais são as características do pacote clang-format-node?
1. Um Drop-in Replacement para o clang-format do Angular
O clang-format-node é um Drop-in Replacement que permite substituir facilmente o pacote Angular/clang-format.
A migração do pacote existente para o clang-format-node é muito simples, e ele pode ser usado imediatamente sem nenhum processo complexo.
2. Só o Node.js já basta, sem dependências extras para usar o Clang
Não há necessidade de dependências adicionais como Python ou C++. Basta ter Node.js para executá-lo com facilidade.
3. Amplo suporte
Oferece suporte abrangente a diversos sistemas operacionais e arquiteturas, versões do Node.js, imagens de runner do GitHub Actions, imagens de build do Docker e muito mais.
4. Configuração simples de CI
Sem configurações complicadas, você pode usar o clang-format-node da mesma forma que qualquer outro pacote Node.js.
5. Build e release automatizados
Sempre que houver uma atualização do clang-format, uma nova versão no npm é lançada automaticamente. O GitHub Actions detecta periodicamente as atualizações, faz o build do pacote e cria um Pull Request.
Formatando código com clang-format e git-clang-format
(O texto abaixo é uma tradução parcial para o coreano de um texto que escrevi em inglês na seção https://clang-format-node.lumir.page/docs/get-started/introduction.)
A importância da formatação de código
Formate o código sempre
A formatação de código é um trabalho muito importante para melhorar a qualidade do código. O ponto central da formatação é manter o código consistentemente formatado para aumentar a legibilidade e a compreensão.
O que é clang-format?
clang-format é uma ferramenta que formata automaticamente arquivos-fonte de linguagens como C e C++, e foi desenvolvida como parte do projeto open source LLVM Clang.
Como funciona
- Criação do arquivo de configuração
Crie um arquivo de configuração (.clang-format) que define o estilo de formatação. - Execução do comando
Ao executar o comandoclang-format, o código-fonte é automaticamente reorganizado de acordo com as regras de estilo definidas.
Principais características
- Suporte a várias linguagens
Suporta diversas linguagens, como C, C++, Java, JavaScript, Objective-C, Protobuf e C#. - Exemplo de comando de formatação
Ao executar esse comando, o arquivoclang-format -i my_source.cppmy_source.cppserá automaticamente formatado conforme o estilo especificado.
Exemplo de formatação de código
// Before formatting
void test(QString&data, bool extraString) {
int i=0;
for (i=0;i<3;i++) {
data+="reallylongstringtoproducealonglineasanexample" + QString::number(i * 1000) + "/filetoload.html";
if (extraString)
{
data += "some-extra";
}
}
}
// After formatting
void test(QString &data, bool extraString)
{
int i = 0;
for (i = 0; i < 3; i++) {
data += "reallylongstringtoproducealonglineasanexample" + QString::number(i * 1000)
+ "/filetoload.html";
if (extraString) {
data += "some-extra";
}
}
}
O exemplo acima mostra como o clang-format formata o código. As regras de formatação podem ser configuradas livremente de acordo com o estilo da equipe.
Problemas do clang-format
O clang-format é uma ótima ferramenta, mas pode causar problemas com o código existente e o histórico de commits.
Principais problemas
- Conflito com o código existente
Ao formatar o arquivo inteiro, até partes não relacionadas à formatação acabam sendo alteradas, gerando mudanças desnecessárias. - Confusão no histórico de commits
Grandes mudanças de formatação podem tornar o histórico de commits mais complexo e dificultar merge de branches, code review e análise de código. - Inconsistência entre código novo e código existente
Ao adicionar código novo a um código já formatado, pode ser difícil manter a formatação.
Solução: git-clang-format
O git-clang-format é uma extensão do Git que ajuda a aplicar formatação apenas ao código alterado. Com isso, você obtém vantagens como:
- Escopo mínimo de formatação: aplica formatação apenas ao código alterado
- Review simplificado: é possível revisar separadamente as mudanças de formatação e as mudanças de desenvolvimento
Como usar o git-clang-format
Instalação
O git-clang-format é fornecido junto com o pacote clang-format-node. Você pode instalá-lo usando o pacote npm clang-format-git.
Fluxo básico de trabalho
- Escreva o código.
- Adicione as alterações ao staging (
git add). - Execute o
git-clang-format.
Exemplo
# Adicionar novo arquivo e colocar alterações em staging
$ git diff --staged
diff --git a/x.cpp b/x.cpp
new file mode 100644
index 0000000..af14ed5
--- /dev/null
+++ b/x.cpp
@@ -0,0 +1,3 @@
+int main() {
+
+}
# Executar git-clang-format
$ git-clang-format
changed files:
x.cpp
# Verificar estado após formatação
$ git status
On branch master
Changes to be committed:
new file: x.cpp
Changes not staged for commit:
modified: x.cpp
Com esse fluxo de trabalho, é possível revisar de forma independente as mudanças de formatação e as mudanças de desenvolvimento. Se você não gostar das mudanças de formatação, também pode revertê-las com git checkout.
Definição de estilo
Você pode configurar o estilo de formatação usando a opção --style.
$ git-clang-format --style=WebKit
$ git-clang-format --style=file # usar o arquivo `.clang-format`
Conclusão
O clang-format é uma ferramenta poderosa, mas no trabalho prático muitas vezes o simples comando clang-format -i não é suficiente. Ao usar o git-clang-format, que aplica formatação apenas às partes alteradas, é possível gerenciar o código com eficiência e simplificar o processo de review.
Como o git-clang-format formata apenas as mudanças, ele permite manter uma base de código limpa e profissional ao mesmo tempo em que oferece um ambiente de desenvolvimento flexível. Ao formatar commits de trabalho ou uma branch inteira, basta usar alguns comandos adicionais do Git para resolver facilmente os problemas de formatação.
Obrigado por ler este texto longo! Desejo um feliz ano-novo a todos os leitores do GeekNews 🙇♂️
- Repositório no GitHub: https://github.com/lumirlumir/npm-clang-format-node
- Site da documentação oficial: https://clang-format-node.lumir.page/
2 comentários
Deixo meu joinha.
Obrigado!!