Porquê automatizar o seu style guide e como fizemos isso para o Java
The coding style and readability set precedents that continue to affect maintainability and extensibility long after the original code has been changed beyond recognition. Your style and discipline survives, even though your code does not. (Uncle Bob, 2008, p.76)
Quem nunca sentiu-se incomodado pela falta de um style guide em um projeto, onde cada desenvolvedor toma para si a decisão de como formatar o seu código?
E, a partir do momento que temos um style guide, precisamos conferir em nossos reviews se os autores dos pull requests seguiram o padrão acordado por todos.
Infelizmente essa acaba sendo uma tarefa trabalhosa e chata e que por muitas vezes não é realizada impecavelmente, pois é muito fácil acabarmos deixando passar uma quebra de linha ou um espaçamento a mais.
Se pararmos para pensar, o style guide é sempre a mesma coisa e, se é sempre a mesma coisa, porquê não automatizarmos isso?
Nosso projeto, nossa IDE e nossa ferramenta de versionamento
Nossa automatização de style guide foi realizada em cima do nosso projeto de back-end, em Java. Esse projeto é nosso webservice único que serve ao nosso aplicativo e também ao nosso site.
Aqui no Prolog nós utilizamos como IDE o Intellij IDEA, da Jetbrains. A escolha da nossa IDE não tem relação com a automatização do style guide mas o Intellij nos permitiu diversas automatizações e facilidades ao longo do tempo. Contudo, isso fica pra outro post.
Para versionamento, utilizamos o GitHub. Nós chegamos em uma época a migrar para o BitBucket, mas por fim retornamos ao GitHub por motivos que estão relatados neste post.
Automatizando o style guide
Automatizar o style guide quer dizer que, de forma automática, alguma ferramenta será responsável por formatar o código e verificar se ele está dentro do padrão acordado. Essa ferramenta pode ser a IDE, ferramenta de versionamento ou qualquer outra que tenha acesso ao código e faça parte do dia a dia do time.
Existem diversos plugins para diferentes IDE’s e repositórios de código, por exemplo, para fazer a verificação do código em tempo real ou no processo de pull request, respectivamente.
Nós optamos por realizar a automatização na nossa IDE, o Intellij, e futuramente movermos também para o GitHub, pra termos certeza de que tudo está conforme nosso padrão. Todo o nosso time utiliza o Intellij, então foi possível fazer isto pela ferramenta. Em um cenário onde nem todos utilizem a mesma, faz sentido e é totalmente válido automatizar apenas no repositório.
Antes de mais nada, é preciso garantir a boa formatação e indentação do código
O intellij permite que você configure nele o seu “code style” (estilo de código). Você pode acessar essas configurações, com seu projeto aberto na IDE, clicando em “File > Settings > Editor > Code Style > Java”.
Aqui você pode configurar espaçamentos, indentações, chaves para suas estruturas condicionais e de repetição e, inclusive, ordenação das informações na sua tela (primeiro variáveis publicas, estáticas e finais; após, variáveis privadas, estáticas e finais…), pela aba “Arrangement”.
É muito importante que essas configurações de formatação sejam realizadas porquê serão elas a serem usadas para formatar e indentar nosso código conforme nosso style guide.
Com nossas configurações de formatação prontas, podemos automatizar esta parte
Com tudo isso configurado, já podemos partir para a primeira automatização. Para isso, usaremos o plugin “Save Actions”.
O plugin save actions é uma adaptação da função nativa do eclipse, save actions. Basicamente, seguindo a ideia do nome, o plugin funciona realizando ações no momento em que o arquivo que está sendo editado, é salvo (ctrl + s, na configuração padrão das IDE’s).
Acredito que o plugin exista também para outras IDE’s não só como plugin, mas também em forma nativa. Se você utiliza outra IDE e não pretende trocar, vale pesquisar para tentar encontrar essa funcionalidade.
Instalado o plugin, abra novamente os settings da IDE (File > Settings), navegue até “Other Settings” e selecione “Save Actions”. Lá você pode selecionar diversas ações para serem ou não serem executadas, muitas envolvendo retirar ou adicionar ponto e vírgula, finals, this, anotações, etc.
O ponto mais importante aqui é deixar marcada as opções “Optmize imports” , “Rearrange fields and methods” e “Reformat only changed code”, essas opções irão apagar imports não utilizados da classe que você estiver mexendo, re-ordenar seu código e reformatá-lo conforme o code style configurado, respectivamente.
As opções “Reformat file” e “Reformat only changed code” fazem na verdade, a mesma coisa. A diferença está em que parte do código será feito. Isso porquê a primeira opção reformata a classe inteira que for salva, enquanto a segunda reformata apenas as partes onde houveram modificações. Isso impede que no seu pull request existam diversas alterações apenas de formatação e dificulte o review.
Partindo para as verificações do style guide
Até agora garantimos que nosso código esteja no formato e ordenamento desejado. Contudo, nem tudo podemos garantir através do Code Style e Save Actions.
Nosso style guide, geralmente, também trata questões sobre nomenclaturas, documentações, números mágicos, etc.
Por conta disso, utilizaremos um segundo plugin para checar se está de fato tudo certo com nosso código, conforme nosso style guide, em tempo real: o CheckStyle-IDEA. Esse plugin possui um repositório aberto no github e permite contribuições: https://github.com/jshiell/checkstyle-idea.
O plugin realiza verificações em tempo real e informa através de warning/errors que algo está fora do padrão.
Configurando o CheckStyle-IDEA
A configuração do plugin é realizada, basicamente, em cima de um xml. O plugin interpreta inúmeras tags padrões, bem configuráveis, para realizar a verificação do código. É possível encontrar na documentação do plugin as respectivas tags e os parâmetros que elas aceitam. As tags ficam na seção “Checks”.
Deixo aqui um exemplo de tags usadas para checar o padrão de nome de alguns tipos de variáveis (public, private, protected) e pacotes, utilizando regex expressions e também o link para o nosso xml de checkstyle.
Nas settings do Intellij é possível acessar a tela de configurações do plugin e indicar qual arquivo ele deve utilizar para realizar as verificações.
Se desejado, é possível utilizar o arquivo de checkstyle da sun o do google. Eles já vem prontos e disponíveis para uso.
O checkbox “Treat Checkstyle errors as warnings” permite você escolher se uma verificação indicada como incorreta pelo plugin será tratada como um warning (ficará amarelo) ou erro (sublinhado em vermelho).
Após criado seu arquivo xml, você pode adicioná-lo para uso no botão de mais “+” dentro da caixa “Configuration file”. Quando abrir a caixinha, você pode selecionar “Use a local Checkstyle file”, para usar um xml dentro da pasta do seu projeto, “Browse”, para exibir a caixa de busca e encontrar e selecionar seu arquivo. Adicione uma “Description” para seu xml, é obrigatório. Ao confirmar, seu arquivo estará disponivel.
Garanta que sua configuração do arquivo fique semelhante a imagem acima: o arquivo default da Sun e do Google não marcados e o seu, marcado.
Com essas configurações e parametrizações, sua IDE já estará verificando em tempo real o seu style guide.
Plus……
Nós também tinhamos algumas dificuldades com a padronização da nossa mensagem de commit. Basicamente, seguimos o padrão:
Onde o type pode ser feat, refact, fix ou docs; O scope é um escopo do nosso projeto; Subject, o titulo da mensagem; Body, o corpo da mensagem; Footer conterá o código do nosso ticket no Jira.
Para saber um pouco mais sobre nossas mensagens de commit e também nome de branches, dá uma olhadinha nesse artigo.
Então, para padronizar, utilizamos o plugin GitToolBox.
Ao fazer download, você terá disponível uma tela de configuração, nos settings do Intellij, chamada “GitToolBox Project”. Lá você pode configurar uma regex para fazer a validação da sua commit message. Além disso, também é possível configurar um tempo especifico para auto fetchs em seu repositório de código.
Concluindo
A automatização e padronização do style guide e também das commit messages dão um up muito grande no projeto como um todo.
Se você já possui uma estrutura para esse fim rodando ou conseguiu realizar a automatização, conta pra gente como ficou!
