Posted on: December 16, 2023 02:23 AM
Posted by: Renato
Categories: Laravel
Views: 243
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 ou short-echo . Não utilize .
| echo 'Using the PHP tag according to PSR-1: "; |
.-----------------------------------------------------------------------------------------------------------------
.--------------------------------------------------
| // side effect: change ini settings | ||
| ini_set('error_reporting', E_ALL); | ||
| // side effect: loads a file | ||
| include "file.php"; | ||
| // side effect: generates output | ||
| echo " | \n"; | |
| // declaration | ||
| function foo() | ||
| { | ||
| // function body | ||
| } |
--------------------------------------------------------------------------------------------------.
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:
| // declaration | |
| function foo() | |
| { | |
| // function body | |
| } | |
| // conditional declaration is *not* a side effect | |
| if (! function_exists('bar')) { | |
| function bar() | |
| { | |
| // function body | |
| } | |
| } |
-----------------------------------------------------------------------------------------------------
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.
| namespace App\Http\Controllers; | |
| class HomeController extends Controller | |
| { | |
| } |
--------------------------------------------------------------------------------------------------------
6. As constantes devem ser declaradas em maiúsculo e separadas por underscore (se necessário).
Vamos ao exemplo:
| namespace Vendor\Model; | |
| class Foo | |
| { | |
| const VERSION = '1.0'; | |
| const DATE_APPROVED = '2012-06-01'; | |
| } |
.----------------------------------------------------------
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.
| namespace Vendor\Package; | |
| use FooClass; | |
| use BarClass as Bar; | |
| use OtherVendor\OtherPackage\BazClass; | |
| // ... additional PHP code ... |
--------------------------------------------------------------------
.
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:
| namespace Vendor\Package; | |
| use FooInterface; | |
| use BarClass as Bar; | |
| use OtherVendor\OtherPackage\BazClass; | |
| class Foo extends Bar implements FooInterface | |
| { | |
| //class body | |
| } |
--------------------------------------------------------------------------------------------------------------
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.
.
| namespace Vendor\Package; | |
| use FooInterface; | |
| use BarClass as Bar; | |
| use OtherVendor\OtherPackage\BazClass; | |
| class Foo extends Bar implements FooInterface | |
| { | |
| public function foo() | |
| { | |
| //function body | |
| } |
----------------------------------------------------------------------------
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:
| namespace Vendor\Package; | |
| use FooClass; | |
| use BarClass as Bar; | |
| use OtherVendor\OtherPackage\BazClass; | |
| class ClassName extends ParentClass implements \ArrayAccess, \Countable | |
| { | |
| // constants, properties, methods | |
| } |
------------------------------------------------------------------------
| namespace Vendor\Package; | |
| use FooClass; | |
| use BarClass as Bar; | |
| use OtherVendor\OtherPackage\BazClass; | |
| class ClassName extends ParentClass implements | |
| \ArrayAccess, | |
| \Countable, | |
| \Serializable | |
| { | |
| // constants, properties, methods | |
| } |
-------------------------------------------------------------------------
.
6. Propriedades não devem ser declaradas com var.
7. A visibilidade das propriedades e métodos devem ser declaradas.
| namespace Vendor\Package; | |
| class ClassName | |
| { | |
| public $foo = null; | |
| } |
--------------------------------------------------------------
| namespace Vendor\Package; | |
| use FooInterface; | |
| use BarClass as Bar; | |
| use OtherVendor\OtherPackage\BazClass; | |
| class Foo extends Bar implements FooInterface | |
| { | |
| public function foo() | |
| { | |
| //function body | |
| } | |
| } |
--------------------------------------------------------------
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.
| namespace Vendor\Package; | |
| class ClassName | |
| { | |
| public function fooBarBaz($arg1, &$arg2, $arg3 = []) | |
| { | |
| // method body | |
| } | |
| } |
.---------------------------------------------------------------------------------------------------------
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:
| if ($expr1) { | |
| // if body | |
| } elseif ($expr2) { | |
| // elseif body | |
| } else { | |
| // else body; | |
| } |
--------------------------------------------------------------------------------------------------------
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:
| switch ($expr) { | |
| case 0: | |
| echo 'First case, with a break'; | |
| break; | |
| case 1: | |
| echo 'Second case, which falls through'; | |
| // no break | |
| case 2: | |
| case 3: | |
| case 4: | |
| echo 'Third case, return instead of break'; | |
| return; | |
| default: | |
| echo 'Default case'; | |
| break; | |
----------------------------------------------------------------------------------------------------------
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!
- https://medium.com/@dhyogoalmeida/psr-padr%C3%B5es-necess%C3%A1rios-para-ter-um-c%C3%B3digo-de-qualidade-92b5d81f70fe
Donate to Site
Renato
Developer