PSR — Padrões necessários para ter um código de qualidade
Introdução
Creio que muito de nós pouco sabíamos que existia um padrão de escrita de código em PHP quando começamos nossa jornada nessa linguagem. A famosa frase: “Funciona? Então tá valendo!” era a que pairava sobre meus pensamentos.
Porém, com o tempo, percebemos (ou deveríamos) evoluir e buscar não somente o funcionamento da aplicação em si, mas sim, a qualidade da escrita do código. Então nos deparamos com as PSRs, um acrônimo de PHP Standards Recommendations (https://www.php-fig.org/psr/), que nos oferece padrões para escrevermos o nosso código.
PHP-FIG. O que é? O que faz?
FIG significa Framework Interoperability Group, formado por um grupo composto por representantes de grandes projetos PHP (CakePHP, Doctrine, Zend Framework, etc.). O objetivo desse grupo é criar padrões que todos esses projetos citados possam adotar. Tais padrões podem ser adotados em nossos projetos e são grandes os benefícios que alcançamos ao utilizá-los, tais como: código legível; fácilidade de dar manutenção; interoperabilidade (componentes de um framework ou pessoa podem ser facilmente integrados em outro).
Neste artigo, vamos falar resumidamente da PSR-1 e PSR-2. Para ter o detalhamento completo e conhecer as demais PSRs, acesso o site oficial da documentação: https://www.php-fig.org/psr/.
PSR-1 — Basic Coding Standard
1. O código PHP deve usar as tags <?php ?> ou short-echo <?= ?>. Não utilize <? ?>.
2. Os arquivos PHP devem usar somente a codificação UTF-8 sem BOM (Byte Order Mark)
UTF-8 sem BOM é a codificação padrão do editores. Sabemos que a codificação de um arquivo pode nos dar dores de cabeça.
3. Você pode declarar classes, funções, constantes, etc. e não causar outros efeitos colaterais ou deve executar a lógica com efeitos colaterais, mas não deve fazer as duas coisas juntas.
O que isso significa? Os arquivos PHP devem ter suas responsabilidades separadas. Vejamos um exemplo:
Neste exemplo, o arquivo está alterando uma configuração do PHP, incluindo um outro arquivo PHP, gerando uma saída e ainda declarando uma função. Vamos à um exemplo correto:
4. Namespace e classes devem seguir um autoloading especificado na PSR-0 e PSR-4 que serão abordadas em uma outra oportunidade.
5. As classes devem ser declaradas utilizando o padrão chamado pelo PHP-FIG de StudlyCaps.
Isso significa que se tenho uma classe que deriva da junção de dois ou mais nomes, como por exemplo, HomeController, o H de home e o C de controller devem ser maiúsculas. Uma classe homeController estaria com o nome errado, não diferente de Homecontroller, que também estaria incorreta.
E se a classe tiver apenas um nome, como por exemplo Home? O correto é exatamente Home, com H maiúsculo.
Este padrão também se aplica à Traits e Interfaces.
6. As constantes devem ser declaradas em maiúsculo e separadas por underscore (se necessário).
Vamos ao exemplo:
7. Propriedades não possuem um padrão exigido.
As PSRs não restringem quanto à definição do uso de nomes para as propriedades.
8. Métodos devem ser declarados em camelCase().
Os métodos devem ser declarados com o caractere da primeira inicial palavra em minúsculos e a demais iniciais em maiúsculo, como por exemplo, o método camelCase(). E se o método tiver somente uma palavra? Então ficaria camel().
PSR-2 — Coding Style Guide
Como vimos, a PSR-1 é simples e sua aplicação é de fácil entendimento. Com a PSR-2 não é diferente, e uma completa a outra. E adivinha qual a primeira especificação da PSR-2? Exato! Isso mesmo, seguir a PSR-1!
1. O seu código deve utilizar 4 espaços para indentação (recuo), e não TABs.
Um dia com certeza alguns de nós já utilizamos o TAB para indentar o nosso código. O problema não é utilizar o TAB em si, mas utilizá-lo sem configurar a quantidade de espaços adequada, no nosso caso, 4 espaços. Graças aos bons editores que temos, como Sublime, Visual Studio Code e etc., podemos configurar sem problemas. E para nos ajudar mais ainda e não restar dúvidas quanto à indentação de nosso código, podemos utililizar uma ferramenta de linha de comando, chamada PHP CS Fixer, que nada mais é do que um projeto open source hospedado no github (https://github.com/FriendsOfPHP/PHP-CS-Fixer) que nos ajuda e muito a aplicar a PSR-1, PSR-2 e mais um pouco.
2. Não deve haver um limite rigoroso (hard limit) no comprimento das linhas, o limite "suave"(soft limit) deve ser de 120 caracteres, as linhas deveriam ser de 80 caracteres ou menos.
Polêmico? Creio que não. Podemos dividir essa recomendação em algumas partes.
Primeira: não deve haver um hard limit.
Segunda: o soft limite deve ser de 120 caracteres em uma linha.
Terceira: o recomendado é que se tenha no máximo 80 caracteres em uma linha.
Mas e agora? É 120 ou 80 caracteres por linha? A RFC 2119 (http://www.ietf.org/rfc/rfc2119.txt) nos ajuda a interpretar as palavras chaves que são utilizadas nas PSRs, conforme o próprio PHP-FIG usa e destaca:
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”,
“SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be
interpreted as described in RFC 2119.
Recomendado significa que: podem existir razões válidas para ignorar este item em particular, ou seja, os 80 caracteres, mas que essa decisão deve ser tomada cuidadosamente para fazer o contrário, ou seja, ultrapassar os 80 caracteres.
3. Deve haver uma linha em branco após o namespace e deve haver outra linha em branco após o bloco de declarações use.
Mais uma coisa: Utilize uma keyword use por declaração.
4. Quanto as classes, deve abrir chaves na próxima linha após a declaração e fechar chave após o corpo da classe. Com exemplo fica fácil:
E para os métodos? A mesma regra aplicada para classes: abrir chaves na próxima linha após a declaração e fechar chaves após o corpo do método.
Ah! Essa regra também se aplica à Interfaces e Traits.
5. As keywords extends e implements devem ser declaradas na mesma linha que o nome da classe. Os implements podem ser declarados na mesma linha ou dividos em várias linhas, onde cada linha é indentada uma vez. O primeiro item da lista deve estar na próxima linha e deve havar apenas uma interface por linha.
Resumidamente, pode ser usado assim:
Ou assim:
6. Propriedades não devem ser declaradas com var.
7. A visibilidade das propriedades e métodos devem ser declaradas.
Obs.: não utilize underscore para indicar a visibilidade do método. Você pode fazer, mas não é o recomendado.
8. Não utilize espaço após o nome do método. Não utilize espaço após a abertura do parêntese, isso também vale para o fechamento.
9. Quando presentes, as keywords abstract e final devem vir antes da visibilidade. E também quando presente a keyword static, esta deve vir após a visibilidade.
10. Abaixo segue a regra geral para as estruturas de controle. Vamos utilizar If, elseif, else e switch,case.
- Deve haver um espaço após a keyword da estrutura;
- Não deve haver espaço após o parêntese de abertura e também não deve haver espaço que anteceda o parêntese de fechamento;
- Deve haver um espaço entre o parêntese de fechamento e a abertura de chaves;
- O corpo da estrutura deve ser indentado uma vez (4 espaços);
- A chave de fechamento deve estar na próxima linha após o corpo;
Vamos aos exemplos do if, elseif e else:
Para switch, case, temos:
- A colocação de parênteses e chaves segue a mesma racional do if;
- O case deve ser indentado uma vez (4 espaços) utilizando como referência o switch;
- A keyword break (ou outra keyword de finalização) deve ser indentada uma vez (4 espaços) utilizando como referência o case;
- Deve haver um comentário informando quando não for utilizado o break. Vamos ver tudo isso aplicado no exemplo abaixo:
Conclusão
Em meio às diversas PSRs existentes, utilizando a PSR-1 e PSR-2 já teremos grandes benefícios se aplicados os padrões que ambas propõem. Sugiro que você a partir de agora comece a aplicar estes padrões e assim escreva códigos mais legíveis e elegantes. Pense no seu código como um livro no qual você é o autor. Um código bem feito traz benefícios para todos, incluindo você e sua equipe.
Think about it!
