Padrões de Codificação¶

Adicionando novos recursos¶

Nenhum novo recurso deve ser adicionado ou disponibilizado sem que tenha seus próprios testes - os quais devem todos passar antes de se submeter seus códigos para o repositório.

Indentação¶

Um tab é usado para a indentação.

Dessa forma, o código deve ser algo parecido com isto:

// base level
    // level 1
        // level 2
    // level 1
// base level

Ou:

$booleanVariable = true;
$stringVariable = "moose";
if ($booleanVariable) {
    echo "Boolean value is true";
    if ($stringVariable == "moose") {
        echo "We have encountered a moose";
    }
}

Estruturas de controle¶

Estruturas de controle são “if”, “for”, “foreach”, “while”, “switch” etc. Veja um exemplo abaixo com “if”:

<?php
if ((expr_1) || (expr_2)) {
    // action_1;
} elseif (!(expr_3) && (expr_4)) {
    // action_2;
} else {
    // default_action;
}

• Em estruturas de controle, deve haver 1 (um) espaço antes do primeiro parênteses e 1 (um) espaço entre o último parênteses e o abre-chaves.

• Sempre utilize chaves para delimitar blocos em estruturas de contole mesmo se elas não forem necessárias. Chaves aumentam a legibilidade do código, o que reduz a possibilidade de erros de lógica.

• O caracter abre-chaves deve estar na mesma linha que a estrutura de controle. Já o fecha-chaves deve estar sempre numa nova linha, e deve ter o mesmo nível de indentação da estrutura de controle. O bloco de instruções delimitado pelas chaves deve começar numa nova linha, e o código nele contido deve ser um nível de indentação maior que o da estrutura de controle.

<?php
// wrong = no brackets, badly placed statement
if (expr) statement;

// wrong = no brackets
if (expr)
    statement;

// good
if (expr) {
    statement;
}

//Good, simple and readable
$variable = isset($options['variable']) ? $options['variable'] : true;

//Nested ternaries are bad
$variable = isset($options['variable']) ? isset($options['othervar']) ? true : false : false;

Chamadas de Funções¶

Funções deve ser chamadas sem espaços entre o nome da função e o abre-parênteses. Deverá ter um espaço entre cada parâmetro na chamda da função:

<?php
$var = foo($bar, $bar2, $bar3);

Como você pode ver neste código, também deve haver um espaço em ambos os lados do sinal de atribuição (=).

Definição de Metódos¶

Exemplo de definição de metódo:

<?php
function someFunction($arg1, $arg2 = '') {
    if (expr) {
        statement;
    }
    return $var;
}

Parâmetros que possuam valores padrões devem ser adicionados por últimos na definição do metódo. Tente fazer que seus metódos sempre retornem algo, pelos menos true ou false - assim facilita a identificação que a chamada ao metódo realmente aconteceu:

<?php
function connection($dns, $persistent = false) {
    if (is_array($dns)) {
        $dnsInfo = $dns;
    } else {
        $dnsInfo = BD::parseDNS($dns);
    }

    if (!($dnsInfo) || !($dnsInfo['phpType'])) {
        return $this->addError();
    }
    return true;
}

De novo, note que deve haver espaços em ambos os lados dos sinais de igual.

Comentando o Código¶

Todos os comentários devem ser escritos em Inglês e deve haver uma clara maneira de identificar o bloco de código comentado.

Comentários podem conter as seguintes tags do phpDocumentor <https://phpdoc.org>:

• @author

• @copyright

• @deprecated Using the @version <vector> <description> format, where version and description are mandatory.

• @example

• @ignore

• @internal

• @link

• @see

• @since

• @version

As tags PhpDoc são bem parecidas com as tags JavaDoc em Java. As tags só são processadas se elas forem a primeira coisa a aparecer numa linha de um bloco de documentação. Por exemplo:

/**
 * Tag example.
 * @author this tag is parsed, but this @version is ignored
 * @version 1.0 this tag is also parsed
 */

<?php
/**
 * Example of inline phpDoc tags.
 *
 * This function works hard with foo() to rule the world.
 */
function bar() {
}

/**
 * Foo function
 */
function foo() {
}

Todos os blocos de comentários, exceto o primeiro bloco de um arquivo, devem ser precedidos com uma linha em branco.

Includindo Arquivos¶

Se for precisar incluir arquivos com classes ou bibliotecas, utilize sempre a função require_once.

Tags PHP¶

Sempre utilize tags do PHP longas (<?php ?>) ao invés de tags curtas (<? ?>).

Convenções de Nomenclatura¶

function longFunctionName() {
}

class ExampleClass {
}

$user = 'John';
$users = array('John', 'Hans', 'Arne');

$Dispatcher = new Dispatcher();

class A {
    protected $_iAmAProtectedVariable;

    protected function _iAmAProtectedMethod() {
       /*...*/
    }
}

class A {
    private $__iAmAPrivateVariable;

    private function __iAmAPrivateMethod() {
        /*...*/
    }
}

$email->from('[email protected]')
    ->to('[email protected]')
    ->subject('A great message')
    ->send();

long_file_name.php

define('CONSTANT', 1);

define('LONG_NAMED_CONSTANT', 2);