Padrões de codificação: algo para farejar

Publicados: 2021-07-19

Algumas questões existem desde o desenvolvimento de software. Devo recuar com tabulações ou espaços? Os padrões de codificação são realmente importantes? Eu realmente preciso perder tempo seguindo algumas regras arbitrárias?

Respectivamente, as respostas a essas perguntas são: guias (obviamente), sim (menos obviamente) e não (mais ou menos).

PHP Codesniffing

A importância dos padrões foi abordada por outros detalhadamente, então não vou entrar em detalhes aqui, mas o ponto crucial é este: consistência interna é desejável dentro de um determinado projeto porque melhora a legibilidade, limita surpresas e pode contribuir para o robustez do código.

Você não precisa “perder tempo” aderindo aos padrões porque existem maneiras de aplicá-los automaticamente!

O que abordarei aqui é um meio de configurar rápida e facilmente a ferramenta autônoma PHP Codesniffer (PHPCS) para projetos WordPress. Isso permitirá que você:

  • Produza um relatório sobre a conformidade com os padrões em seu código
  • Resolva automaticamente uma ampla variedade de problemas de conformidade

Implementaremos os padrões do WordPress nos exemplos a seguir.

Instalando

Pré-requisitos:

  • Acesso ao terminal (usuários do Windows podem ter sucesso com o Bash para Windows, mas isso não foi testado)
  • Gerenciador de pacotes Composer

Embora seja possível instalar o PHPCS sozinho, ele não oferece suporte para WordPress por padrão. Para isso, vamos instalar os padrões de codificação WordPress (WPCS) rapidamente chamados.

Primeiro, navegue para onde deseja instalar o WPCS para uso global.

 $> cd / caminho / para / onde

Instale o pacote com o composer.

 $> compositor criar projeto wp-coding-standards / wpcs --no-dev

Neste ponto, poderíamos mergulhar e começar a usar o WPCS, mas existem alguns sinalizadores a serem definidos cada vez que executamos o comando. Vamos configurar alguns apelidos para sua conveniência.

Abra .profile de seu diretório inicial em seu editor favorito (ou crie-o se ele não existir) e adicione o seguinte:

 # Padrões de codificação WP
export PATH = $ PATH: "/ path / to / where / wpcs / vendor / bin"
alias wpcs = 'phpcs --standard = WordPress --extensions = php
alias wpcbf = 'phpcbf --standard = WordPress --extensions = php

Adicionamos dois aliases aqui - um para phpcs (que encontra e exibe falhas de conformidade) e um para phpcbf (que corrige automaticamente vários problemas encontrados por phpcs). As opções adicionais fazem o seguinte:

–Standard = WordPress - aplica os padrões do WordPress (definidos em WPCS)

–Extensions = php - arquivos PHP de destino apenas (PHPCS é direcionado a PHP, CSS e JS por padrão)

Reinicie o Terminal (ou fonte .profile ) e o WPCS está pronto para farejar seu código!

Cheirando

Para produzir um relatório de detecção em um arquivo, execute o seguinte:

 $> wpcs /path/to/your/php/project/file.php

Isso irá gerar o relatório no terminal. Como alternativa, você pode enviar isso para um arquivo:

 $> wpcs /path/to/your/php/project/file.php> output.txt

The Sniff Report

A saída do sniff WPCS será mais ou menos assim:

Relatório PHP Codesniffer

Há uma boa quantidade de informações compactadas aqui, mas é bem organizado. Vamos revisar o que temos:

  • O arquivo de destino
  • Um resumo de quantos erros / avisos foram encontrados e o número de linhas afetadas
  • Uma lista de problemas encontrados, com níveis de gravidade e descrições
  • Uma indicação de quantos problemas o phpcbf pode resolver automaticamente (basicamente todos os problemas com um [x])

Como era de se esperar, o PHPCS não pode dar conta de tudo. Ele não fará suposições sobre a escolha da pontuação em comentários e certos tipos de formatação de código, mas pode lidar com uma ampla variedade de problemas para você.

Um bom bônus é que as regras do WordPress permitem que o PHPCS detecte problemas específicos do WordPress, incluindo o uso indevido de funções.

Consertando

Resolver problemas automaticamente não poderia ser mais fácil:

 $> wpcbf /path/to/your/php/project/file.php

Um breve resumo é gerado:

Saída do fixador de código PHP

Quaisquer erros restantes precisam ser corrigidos manualmente, mas você normalmente descobrirá que uma boa parte dos problemas foi resolvida.

Regras Customizadas

Você também pode desejar personalizar o conjunto de regras, excluir determinados diretórios em seu projeto e assim por diante. Os documentos do conjunto de regras anotado do PHPCS fornecem exemplos de todas as mudanças que você pode fazer, mas falando de maneira geral, você apenas:

  1. Crie um arquivo de conjunto de regras
  2. Faça referência a ele no comando PHPCS

Aqui está um exemplo de arquivo de conjunto de regras:

 <? xml version = "1.0"?>
<ruleset name = "WordPress Coding Standards">
    <description> Padrões WordPress personalizados. </description>
    <regra ref = "WordPress">
        <exclude name = "Generic.Formatting.MultipleStatementAlignment.NotSameWarning" />
    </rule>
    <exclude-pattern> * / bin / * </exclude-pattern>
    <exclude-pattern> * / node_modules / * </exclude-pattern>
    <exclude-pattern> * / tests / * </exclude-pattern>
</ruleset>

No exemplo, fizemos o seguinte:

  • Referência ao conjunto de regras do WordPress (do WPCS)
  • Excluiu uma regra
  • Alguns diretórios excluídos

O arquivo do conjunto de regras pode ser colocado em qualquer diretório a partir do qual você está chamando o WPCS (o projeto, tema ou raiz do plug-in é geralmente sensato) e referenciado por meio de um sinalizador. Atualize a sinalização –standard em seu .profile, assim:

 # Padrões de codificação WP
export PATH = $ PATH: "/ path / to / where / wpcs / vendor / bin"
alias wpcs = 'phpcs --standard = codesniffer.ruleset.xml --extensions = php
alias wpcbf = 'phpcbf --standard = codesniffer.ruleset.xml --extensions = php

Para verificar quais regras estão sendo sinalizadas quando você executa o WPCS, basta executá-lo com o sinalizador -s assim:

 $> wpcs -s /path/to/your/php/project/file.php

Qual o proximo?

O guia acima irá capacitá-lo a realizar verificações de conformidade de padrões ad-hoc em seu projeto WordPress, mas se você quiser integrá-lo ao seu ciclo de desenvolvimento padrão, a próxima etapa lógica é a automação.

Considere a integração do PHPCS em um executor de tarefas, como gulp ou grunt (módulos PHPCS estão disponíveis para ambos) ou, de outra forma, integrá-lo ao pipeline de compilação de CI / CD.

Para obter ajuda com o desenvolvimento e design da web, entre em contato conosco hoje.

Se precisar de ajuda com o seu, não hesite em nos contatar.