PADRAO DE CODIGO E COMMIT

Este guia descreve o estilo de codificação PHP para a colaboração no projeto Payment Gateway da comunidade Beer And Code. É provável que desenvolvedores e equipes individuais tenham suas próprias visões fortes sobre determinados estilos de codificação, portanto esse conjunto de documentos deve ser visto como um guia, não um livro de regras. Dito isto, tudo o que está documentado aqui é a preferência dos desenvolvedores principais, portanto, considere os pontos antes de enviar solicitações pull requests (PR). O objetivo deste documento é ajudar a orientar o estilo das contribuições de código para manter um estilo consistente no repositório, definir e justificar as decisões tomadas dentro dele.

QUANTO AO CODIGO

O código de exemplo a seguir mostra uma visão geral do estilo proposto neste guia:

 <?php
    namespace FastFood\Page;
    
    use FastFood\Logic\OrderLogic;
    use FastFood\Menu\MenuFactory;
    use Vendor\Food\FoodOrderInterface;
    
    class OrderPage extends OrderLogic implements FoodOrderInterface {
        const TYPE_MAIN = "order-type-main";
        const TYPE_VEGETARIAN = "order-type-vegetarian";
        const TYPE_VEGAN = "order-type-vegan";
        const TYPE_GLUTENFREE = "order-type-glutenfree";
    
        private OtherClass $menu;
    
        public function go():void 
              {
            $this->menu = MenuFactory::create($_GET["type"]);
            $this->sampleMethod($this->menu->getName(), $this->menu->getSize());
            $output = $this->longMethodWithManyArgs(
                $this->getDefaultSize(),
                123,
                "example"
            );
        }
    
        private function sampleMethod(string $name, int $size = 0):void 
              {
            $maxSize = OtherClass::getMaxSize($name);
    
            if($size === 0) {
                $this->menu->fillEmpty(OtherClass::getDefault());
            }
            elseif($size > $maxSize) {
                $size = $maxSize;
            }
            else {
                switch($size) {
                case OtherClass::SIZE_INDIVIDUAL:
                    $this->menu->setStyle("individual");
                    break;
    
                case OtherClass::SIZE_FAMILY:
                    $this->menu->setStyle("family");
                    break;
    
                default:
                    $this->menu->setStyle(Menu::SIZE_DEFAULT);
                    break;
                }
            }
        }
    
        public function longMethodWithManyArgs(
            int $firstNumber,
            int $secondNumber = 0,
            string $exampleString = null
        ):Menu 
              {
            $duplicate = MenuFactory::create($this->menu->getType());
    
            if($duplicate->getSize() !== 0
            && $duplicate->name === $exampleString) 
                {
                return MenuFactory::createDefault();
            }
    
            return $duplicate;
        }
    }

CONCEITOS GERAIS

A primeira linha de todos os arquivos .php deve ser exatamente "<?php"
Nunca use a tag PHP de fechamento (?>)
Nunca use tags curtas (short tags) do PHP
Todos os arquivos devem usar apenas UTF-8, sem BOM
Sempre use o fuso horário America/Sao_Paulo para armazenar data e hora
Todo arquivo de biblioteca .php deve conter exatamente uma classe
Todo arquivo de biblioteca .php deve ser livre de efeitos colaterais
Em arquivos e códigos, use palavras no singular (por exemplo, item, stylesheet, user) em vez de palavras no plural
Evite notação húngara, onde nomes de arquivos / variáveis que indicam seu tipo
Use camelCase para nomear variáveis
Nunca use variáveis globais
Propriedades sempre devem ser declaradas
As variáveis sempre devem ser declaradas no topo do bloco em que são usadas
Evite usar a palavra-chave final, a menos que seja necessário
Evite chamar funções no namespace global
Os códigos de programação, variáveis e funções deverão ser escritos em inglês

INDENTACAO

Use 4 espaços ao invés de tabulação (PSR-12)
Evite blocos de código com "dupla indentação" onde nenhuma indentação é necessária para facilitar a leitura
Não deixe espaços em branco no final das linhas
Seja o mais rigoroso possível para aplicar 80 linhas de caracteres

CHAVES E COLCHETES

As chaves de abertura DEVE seguir sua própria linha (PSR-12)
As chaves de fechamento devem sempre ser colocadas no início de sua própria linha (PSR-12)
Toda condicional if() deve conter chaves de abertura e fechamento, ainda que o corpo possua apenas 1 linha.
Um nível de indentação deve ser aplicado dentro e somente dentro das chaves
Os condicionais entre colchetes não devem obter indentação extra ao quebrar em linhas separadas
Nunca deixe declarações condicionais sem restrições ou sem indentação

ESPACOS

Nenhum espaço extra deve ser colocado após uma palavra-chave da estrutura de controle ou nome da função
Os colchetes de abertura não devem ter espaço depois; os colchetes de fechamento não devem ter espaço antes
Vírgulas que separam listas de variáveis devem ter um espaço ou nova linha depois, sem espaço em branco antes
Um espaço deve envolver operadores binários e ternários, mas não unários
Um espaço deve envolver todos os operadores de tipo

DIRETORIOS, ARQUIVOS E NAMESPACES

Diretórios e arquivos devem ser mapeados para namespace ou web (view)
Os espaços para nome devem ser mapeados para os caminhos de arquivo, conforme PSR-4
Arquivos e diretórios devem estar em minúsculas com hífen onde não forem mapeados para namespace
Os arquivos e diretórios mapeados para namespace devem usar UpperCamelCase
Arquivos e diretórios mapeados na Web devem usar palavras em minúsculas e hifenizadas

CLASSES

Uma classe só deve ser carregada automaticamente - nunca use require ou include
Constantes só devem ser declaradas em uma classe (deve atender somente à classe declarada)
As constantes devem usar UPPERCASE_UNDERSCORED
As propriedades devem usar $camelCase
Os métodos devem usar camelCase()
As classes devem ter todos ou nenhum membro estático
Todos os parâmetros devem definir seu tipo sempre que possível
Todos os métodos devem definir seu tipo de retorno sempre que possível
Os métodos devem evitar ficar mais de 20-50 linhas

COMENTARIOS

Se possível evite comentários, pois um um bom código não precisa de comentários (se possível leia o livro Código Limpo)
Para comentários embutidos, devem ser usados comentários com barra dupla (//)
Comentários embutidos não devem ter indentação, começando na coluna 1
Comentários embutidos podem abranger várias linhas, prefixadas com a barra dupla
Os comentários de bloco devem ser usados apenas para fornecer documentação de classe e método na forma de blocos de documentos
Os comentários, juntamente com os docblocks, devem ser esparsos e pesados para evitar documentação obsoleta

ESTRUTURA DE DADOS

As estruturas de dados que representam coleções devem ser acessíveis por array, collections e / ou iterables
Estruturas de dados que representam itens individuais devem usar funções getter
Arrays associativos devem ser usadas apenas para pares simples de valor-chave
Mova arrays associativos para um object com getter / setter sempre que possível
Classes estáticas devem ser usadas apenas quando verdadeiramente não tiverem estado

QUANTO AOS COMMITS

A princípio vamos trabalhar apenas com feat (feature, novo recurso) e fix (hotfix, correção de problemas)
O título (primeira linha do commit) deverá estar no imperativo (adiciona) e não adicionado.
A mensagem do commit deverá ser obrigatoriamente em português, conforme definido por todos em live

O commit deverá seguir a seguinte estrutura:

  <tipo>[escopo opcional]: <descrição>
  <corpo opcional>
  <rodapé opcional>

Com base nisso, um commit de hotfix ficaria assim: fix(containers/profile.php): ajusta o argumento da função getPaymentMethods

getPaymentMethods usava o tipo XPTO para receber argumento. Agora recebe o argumento correto do tipo FOO.

Resolve a issue #132

OBS.: o escopo está opcional, pois quando for um novo recurso (feat) pode ser que entre vários arquivos, inviabilizando informar todos no escopo.

EXEMPLOS

Nomeacao incorreta de Namespaces e Classes

Nome Completo da Classe	Nome Não Qualificado	Observações
\Neos\Flow\Session\Php	Php	A classe não é uma representação do PHP
\Neos\Cache\Backend\File	File	A classe não representa um arquivo
\Neos\Flow\Session\Interface	Interface	Interface é uma palavra-chave reservada
\Neos\Foo\Controller\Default	Default	Default é uma palavra-chave reservada
\Neos\Flow\Objects\Manager	Manager	Nome de classe não especifica de forma clara seu objetivo

Nomeacao correta de Namespaces e Classes

Nome Completo da Classe	Nome Qualificado	Observações
\Neos\Flow\Session\PhpSession	PhpSession	Essa é uma sessão PHP
\Neos\Cache\Backend\FileBackend	FileBackend	Uma classe pertencente ao escopo de Backend
\Neos\Flow\Session\SessionInterface	SessionInterface	Interface para sessões
\Neos\Foo\Controller\StandardController	StandardController	Um controller padrão
\Neos\Flow\Objects\ObjectManager	ObjectManager	Classe pertencente ao escopo de Objects

Edge Cases

Forma Não Qualificada	Forma Qualificada	Observações
\Neos\Flow\Mvc\ControllerInterface	\Neos\Flow\Mvc\Controller\ControllerInterface	Uma vez que se trata de uma interface concernente a todos os arquivos do namespace Controller
\Neos\Cache\AbstractBackend	\Neos\Cache\Backend\AbstractBackend	Uma vez que se trata de uma interface concernente a todos os arquivos do namespace Backend

Observação: Ao especificar nomes de classe para PHP, sempre faça referência ao espaço para nome global dentro do código no espaço de nomes usando uma barra invertida à esquerda. Ao fazer referência a um nome de classe dentro de uma string (por exemplo, dado ao método get do ObjectManager, em expressões pointcut ou em arquivos YAML), nunca use uma barra invertida à esquerda. Isso segue a noção nativa do PHP de nomes em strings sempre sendo vistos como totalmente qualificados.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly