Languages: English • Italiano • コーディング基準 日本語 Português do Brasil • 中文(简体) • (Add your language)

Algumas partes legadas da estrutura de código do WordPress para marcação de PHP estão despadronizadas. O WordPress está trabalhando para, gradualmente, melhorar isto ajudando os usuários a manter um estilo consistente então o código poderá permanecer limpo e de fácil leitura.

Tenha esses tópicos em mente quando estiver codificando para o WordPress, seja para desenvolvimento pesado, Plugins, ou WordPress Themes. As orientações são similares ao Pear standards de várias formas, mas diferem em alguns aspectos.

Veja também esse post na lista wp-hackers.

Tem também uma página com os padrões propostos para Inline Documentation.

Aspas simples e duplas 

Use aspas simples e duplas quando apropriado. Se você não estiver tratando nada na string, use use aspas simples. Você nunca deve escapar aspas HTML numa string, porque você apenas precisa alternar entre os tipos de aspas, assim:

echo '<a href="/link/estatico" title="Yeah yeah!">Nome do link</a>';
echo "<a href='$link' title='$titulodolink'>$nomedolink</a>";

A única exceção é no JavaScript, que as vezes reques aspas simples ou duplas. Textos que venham dentro de atributos devem passar pelo attribute_escape() assim as aspas simples ou duplas não fecham o atributo e invalidam o XHTML causando um problema de segurança.

Indentação 

Sua indentação deve sempre refletir uma estrutura lógica. Use tabs reais e não espaços, pois isso permite maior flexibilidade entre clientes.

Exceção: se você tem um bloco de código que seja mais legível se estiver alinhado, use espaços:

[tab]$foo   = 'algumvalor';
[tab]$foo2  = 'algumvalor2';
[tab]$foo34 = 'algumvalor3';
[tab]$foo5  = 'algumvalor4';

Regra de ouro: tabs devem ser usadas no início das linhas e espaços devem ser usados no meio das linhas.

Estilo das Chaves 

Chaves devem ser usadas em multiplos blocos:

if ( condicao ) {
    acao1();
    acao2();
} elseif ( condicao2 && condicao3 ) {
    acao3();
    acao4();
} else {
   acaopadrao();
}

No mais, se você tiver um bloco muito grande, considere quebrá-lo em dois ou mais blocos ou funções.

consider whether it can be broken into two or more shorter blocks or functions. Caso seja realmente necessária a existência desse longo bloco, por favor ponha um pequeno comentário no final para que as pessoas percebam de relance o que aquela chave de fechamento está fechando -- normalmente isso é apropriado para blocos lógicos, maiores que cerca de 35 linhas, mas qualquer código que não seja intuitivamente óbvio pode ser comentado.

blocos de uma linha apenas pode omitir as chaves para ficarem mais concisos:

if ( condicao )
    acao1();
elseif ( condicao2 )
    acao2();
else
    acao3();

se qualquer um dos blocos relacionados tiver mais de uma linha então todos os blocos relacionados devem possuir chaves :

if ( condicao ) {
    acao1();
} elseif ( condicao2 ) {
    acao2a();
    acao2b();
}

loops devem sempre conter chaves para melhorar a legibilidade, e permitir poucas linhas de edição para posteriores correções ou adição de novas funcionalidades :

foreach ( $itens as $item ) {
    processar_item( $item );
}

include_once vs. require_once 

Aprenda a diferença entre include_once e require_once, e use o mais apropriado. Para citar a php página do manual php sobre o include(): "Os dois construtores são identicos em todos os aspectos exceto em como eles tratam as falhas. include() produz um Alerta (Warning) enquanto o require() resulta num Erro Fatal (Fatal Error)." Erros Fatais interrompem a execução do script.

Expressões regulares

Expressões regulares compatíveis com Perl (PCRE, funções preg_) devem ser usadas preferencialmente às homólogas POSIX. Nunca use o alternador /e, ao invés dele use preg_replace_callback.

Não utilize as abreviações PHP 

Nunca use as tags de abertura do PHP abreviadas (<? ... ?> ou <?=$var?>). Sempre use as tags inteiras (<?php ... ?>). Tenha certeza de remover todos os espaços em branco após o fechamento das tags.

Uso de espaços 

Sempre ponha espaços após as vírgulas e em ambos os lados das atribuições de operadores lógicos como "x == 23", "foo && bar", "array( 1, 2, 3 )", assim como em ambos os lados dos parentesis de abertura e fechamento de blocos if, elseif, foreach, for e switch (ex. foreach ( $foo as $bar ) { ...). Quando definindo funções, faça assim: function minhafuncao( $param1 = 'foo', $param2 = 'bar' ) { e quando chamando uma funcao, faça assim: minhafuncao( $param1, funcparam( $param2 ) );

Formatado declarações SQL 

Quando formatando declarações SQL você pode quebrá-la em várias linhas e indentá-la caso ela seja complexa. Apesar de a maioria das declarações funcionarem bem em uma linha. Sempre capitalize as partes das instruções SQL como UPDATE ou WHERE.

Funções que atualizam o banco de dados devem esperar que seus parâmetros não tenham as barras de escape (\) quando passadas. O escape de ser feito o mais próximo da hora da consulta possível, de preferência usando $wpdb->prepare()

$wpdb->prepare() é um método que cuida do escape, aspas, e fusão dos inteiros (int-casting) para as consultas SQL. Ela usa um subconjunto de estilo e formação da sprintf(). Exemplo :

$var = "perigo'"; // dado cru que precise, ou não, ser escapado
$id  = algum_numero_foo(); // dado que esperemos que seja inteiro, mas não temos certeza

$wpdb->query( $wpdb->prepare( "UPDATE $wpdb->posts SET post_title = %s WHERE ID = %d", $var, $id ) );

%s é usado para marcadores de texto e %d é usado para marcadores inteiros. Note que eles não possuem 'aspas'! $wpdb->prepare() irá cuidar do escape e das aspas para nós. O benefício disso é que não precisamos nos lembrar de usar $wpdb->escape() manualmente, e também que fica de fácil leitura quer os dados tenham sido escapados ou não, porque isso acontence logo quando a consulta é feita.

Veja Validação de Dados para o Banco de Dados para mais informações.

Consulta Banco de Dados 

Evite acessar o banco de dados diretamente. Se existir alguma função que consiga o dado que você precisa, use-a. Abstração do banco de dados (usando funções ao invés de consultas) ajuda a manter seu código sempre compatível e, em casos em que o resultado é guardado na memória (cache), ela pode ser muito mais rápida. Se você precisar tocar no banco de dados, entre em contato com alguns desenvolvedores postando uma mensagem no wp-hackers mailing list. Eles podem considerar criar uma função para as novas versões do WordPress que atenda essa funcionalidade que você precisa.

Variáveis, funções, nomes de arquivos, e operadores 

Use letras minúsculas em nomes de variáveis e funções (nunca CamelCase). Separe palavras por sublinhados (underscores).

function algum_nome( $alguma_variavel ) { [...] }

Arquivos devem ser nomeados descritivamente usando letras minúsculas. Hífens devem separar as palavras.

nome-do-meu-plugin.php

Se você não for usar uma variável mais de uma vez, não a crie. Isso inclui consultas. Sempre use as funções da wpdb Class quando interagir com o banco de dados.

Tudo bem em usar operadores ternarios, mas sempre teste se a declaração é verdadeira (true), não false (false). Caso contrário fica confuso.

// BOM exemplo:
// (se declaracao for verdadeira) ? (faca isso) : (se for falsa, faca isso);
$generomusicao = ( 'jazz' == $musica ) ? 'legal' : 'blah';

Outro ponto importante no exemplo acima, quando fizer comparação lógica sempre ponha a variável do lado direito, como acima. Se você esquecer um igual, um erro será lançado ao invés da avaliação ser verdadeira e a declaração ser executada. Isso não toma nenhum tempo extra para ser feito, então se evitar um erro já vale a pena.

Valores de sinalização de argumentos de função auto-explicativos 

Prefira valores em string a apenas true e false quando chamar funções.

//RUIM
function comer( $oque, $devagar = true ) {
    ...
}
comer( 'cogumelos' );
comer( 'cogumelos', true ); // O que significa true?
comer( 'comida de cachorro', false ); // O que significa false? O oposto de true?

Já que o PHP não suporta argumentos em forma de nomes, os valores dos sinalizadores não tem significados e toda vez que aparece uma função como essa nós temos que pesquisar pela definição da função. O código pode ficar mais legível se usarmos textos descritivos, ao invés de boleanos:

//BOM
function comer( $oque, $velocidade = 'devagar' ) {
    ...
}
comer( 'cogumelos' );
comer( 'cogumelos', 'devagar' );
comer( 'comida de cachorro', 'rapido' );