Drupal Coding Standards para equipes distribuídas
Quando estamos trabalhando em equipe é muito importante que tenhamos padrões bem definidos para que o time possa focar no que realmente importa:
Entregar valor ao cliente.
Essa preocupação com padrões visa otimizar o processo e evitar que o projeto venha a se tornar cada vez mais difícil de manter, de evoluir e inovar. Principalmente quando trabalhamos com modelos similares ao Fluxo Unificado, onde temos pessoas diferentes, em lugares diferentes, trabalhando na mesma base de código e/ou em múltiplos projetos. Isso gera uma complexidade maior para manter todos os membros da equipe atualizados e confortáveis para desenvolver a sua função.
Devemos lembrar que código compartilhado significa responsabilidade compartilhada. Então devemos presar pela qualidade e simplicidade, assim como já estamos acostumados quando colaboramos com projetos de Software Livre e Open Source.
Para conseguirmos diminuir a quantidade de WTF por minuto nos nossos projetos, podemos começar com uma coisa simples:
Padrões de desenvolvimento (Coding Standards).
Se essa é a primeira vez que você ouve falar o termo “WTF por minuto”, não deixe de dar uma olhada na comic do Thorn Holwerds que ilustra isso de uma maneira muito descontraída: The only valid measurement of code quality: WTFs per minute.
O Drupal oferece uma documentação bem completa sobre padronização de código. Você pode conferir em Drupal coding Standards. Pra quem trabalha com Drupal diariamente e/ou contribui para o projeto é muito importante ter esses padrões bem fixados, porém, isso pode ser um processo lento. Para facilitar esse processo temos o módulo coder para nos ajudar.
Confira abaixo o passo-a-passo da instalação:
Primeiramente precisamos installar o Composer.
O que é o Composer?
O Composer é uma ferramenta para gerenciamento de dependência em PHP. Ele permite que você declare as bibliotecas/dependências que seu projeto precisa e vai instalá-las para você quando necessário.
Caso você não conheça o Composer, essa ferramenta é muito utilizada pela comunidade PHP e o Drupal 8 já está aproveitando os benefícios do Composer. Então reserve um tempinho para estudar e se acostumar com essa ferramenta.
Para instalar a ultima versão do Composer você pode seguir os passos abaixo:
curl -sS https://getcomposer.org/installer | php
Caso você não tenha o comando curl, você pode instalar da seguinte maneira:
php -r “readfile(‘https://getcomposer.org/installer');" | php
Este instalador irá apenas checar suas configurações do php.ini, alertá-las caso haja alguma configuração incorreta, e então baixar a ultima versão do composer.phar no diretório em questão.
Se você quiser que o Composer esteja disponível globalmente você vai precisar move-lo para o diretório /usr/bin com o seguinte comando (Isso pode variar dependendo do seu sistema operacional):
sudo mv [cpho para o composer.phar]/composer.phar /usr/bin/composer
Agora execute o comando composer para ver se tudo está OK.
Ao rodar o comando você deve receber algo similar ao seguinte:
Para mais detalhes acesse a página do Composer em https://getcomposer.org
Se você usa PHPStorm como IDE para PHP, aqui tem um vídeo bacana de como configurar o Composer no PHPStorm:
Depois do Composer instalado, precisamos instalar o Coder.
O que é o Coder?
O Coder não é exatamente um módulo para o Drupal, mas sim uma ferramenta que pode ser utilizada via linha de comando ou alguma IDE.
O objetivo dele é validar o código de acordo com os padrões de codificação do Drupal e outras boas práticas de desenvolvimento.
O modulo Coder contém “sniffs” para o PHP CodeSniffer. Esses “sniffs” comunicam ao PHP CodeSniffer onde o código está ou não de acordo com os padrões do Drupal. Como ele utiliza o PHP CodeSniffer, ele te permite inclusive fazer as correções das violações de padrão de maneira automatizada através do comando phpcbf.
É extremamente recomendado instalá-lo em um lugar central, dessa forma, você não terá que fazer o download do módulo novamente quando estiver em outro site em Drupal. Para isso podemos utilizar o Composer e instalar o Coder globalmente e já instalamos de bandeja o PHP_CodeSniffer por ser uma dependência do Coder. Dessa forma ele estará no diretório home do seu usuário (~/.composer) e estará disponível para todos os projetos que você estiver trabalhando.
Drupal 7
Neste caso iremos utilizar a versão 7.x-2.x, logo, devemos executar o seguinte comando:
composer global require drupal/coder:\>7
Drupal 8
No caso do release para Drupal 8, iremos utilizar a versão 8.x-2.x, assim, iremos executar o seguinte comando:
composer global require drupal/coder:\>8
Se você preferir a versão mais recente do Coder, neste momento a 8.x-2.x dev, você precisará editar o arquivo ~/.composer/composer.json e adicionar a propriedade de versão mínima estável para dev:
{ “minimum-stability”: “dev”}
Agora sim podemos instalar a versão 8.x-2.x (versão dev) do Coder.
composer global require drupal/coder:dev-8.x-2.x
Após executar este comando você deve receber uma mensagem similar ao seguinte:
Como instalamos o Coder com o Composer, ele já baixou a dependência do PHP_CodeSsniffer. Dessa forma já temos o comando phpcs disponível e você já pode fazer um teste com o seguinte comando:
~/.composer/vendor/bin/phpcs --standard=/home/[seu usuário]/.composer/vendor/drupal/coder/coder_sniffer/Drupal [caminho para o arquivo]/exemplo.module
Para não termos que sempre passar o caminho completo para o phpcs (~/.composer/vendor/bin/phpcs), vamos adicionar o composer no nosso $PATH com o seguite comando:
echo “export PATH=$HOME/.composer/vendor/bin:$PATH” >> ~/.bashrc
Pronto!
Como o comando fica bem longo e difícil de memorizar, podemos configurar um alias de Shell.
Caso você esteja utilizando o bash, basta adicionar no arquivo ~/.bashrc ou no arquivo ~/.bash_aliases a linha abaixo:
alias drupalcs=’phpcs --standard=[caminho para o módulo Coder]/coder_sniffer/Drupal -- extensions=php,module,inc,install,test,profile,theme,js,css,info,txt’
Pra facilitar ainda mais você pode executar o comando abaixo direto no terminal:
echo “alias drupalcs=’phpcs --standard=[caminho para o módulo Coder]/coder_sniffer/Drupal --extensions=php,module,inc,install,test,profile,theme,js,css,info,txt’” >> ~/.bashrc
Após adicionar o alias precisamos aplicar as atualizações do nosso .basrc para pegar nosso novo alias. Para isso basta executar o seguinte comando:
source ~/.bashrc
Caso você esteja utilizando zsh no lugar do bash, acesse a página da documentação do Coder no drupal.org para mais detalhes (em inglês).
Agora, vamos falar sobre o PHP_CodeSniffer.
O que é CodeSniffer?
CodeSniffer é uma ferramenta análise estática de código. Isso permite que um conjunto de regras ou padrões sejam aplicados ao código fonte. Estas regras podem ser usadas para detectar erros comuns de programação ou inconformidades com os padrões, ele também pode ser usado para definir um conjunto de padrões de codificação para seu projeto.
O PHP_CodeSniffer vem com um conjunto de normas já definidas de codificação que são regularmente usadas.
Estas são:
- MySource
- PEAR
- PHPCS
- Squiz
- Zend
Analisar seu código usando uma ou mais destas normas vai destacar como o código que você forneceu está em relação as normas da codificação padrão. A partir de agora sempre que você escrever um código para o Drupal você poderá rodar o drupalcs em sobre o arquivo em questão.
Exemplo:
drupalcs [caminho para o arquivo]/example.module
Para otimizar ainda mais o processo, podemos utilizar o hook de pre-commit do git para executar essa validação automaticamente.
Uma ótima maneira de fazer isso é utilizando o projeto Git Pre-commit hooks do Drupal.
Esse projeto contém tudo que você precisa para ter seu código validado sempre que fizer um novo commit.
Como instalar o Git pre-commit hooks?
A “instalação” desse hooks é muito simples. Basta copiar os arquivos pre-commit para dentro do diretório .git/hooks/ do seu projeto.
Agora, quando você executar git commit o script de pre-commit será executado, ele irá encontrar o arquivo pre-commit_phpcs e irá exectutá-lo. O script pre-commit_phpcs vai analisar arquivos presentes no commit em questão e irá te retornar um feedback sobre os erros e avisos, caso existam.
A partir de agora não há mais desculpas para não seguir os padrões de códificação do Drupal. Apesar de extremamente não recomendado, podem haver casos em que você precise fazer um commit dos arquivos sem que seja feita a validação os padrões de código.
Para isso você pode utilizar o argumento--no-verify, dessa maneira o git não irá executar os hooks de pré commit.
Ex.:
git commit --no-verify
Mas lembre-se que isso deve ser utilizado em casos raros e você deve tomar muito cuidado para não criar o mal hábito de não validar os padrões de codificação do seu código.
Agora você já tem as ferramentas necessárias para começar a desenvolver com a segurança de que seu código estará de acordo com as melhores práticas de desenvolvimento da comunidade PHP/Drupal. Deste forma podemos começar a praticar e com o tempo estes padrões de codificação se tornarão tão habituais que você já irá começar a usar o WTF por minuto quando estiver fazendo review dos seus códigos antigos e dos códigos que você estiver revisando no futuro.
Para finalizar, uma boa forma de melhorar a qualidade e legibilidade do seu código, sempre tenha em mente que o seu código deve ser autoexplicativo, ou seja, você não tem que ter a necessidade de explicar (verbalmente ou via comentários no código) o que cada rotina está prestes a fazer.
Uma boa forma de começar é utilizar nomes de classes, métodos e variáveis que ajudem no entendimento da finalidade e do que cada um desses itens se propõem. Assim, quem ler o seu código terá mais clareza do que está acontecendo e irá entender melhor, sem a necessidade de ficar indo e voltando para saber o que está acontecendo. Sem contar que você terá menor necessidade de adicionar comentários para explicar para o seu Eu do futuro, ou para seus colegas, o que cada rotina do seu código está fazendo.
