WordPress logo

Todo bom projeto tem um certo padrão de codificação, que é o que vai tratar da maneira como seu código deve ser escrito, seja por um espaço a mais, pelo método que as chaves são colocadas nas estruturas condicionais, nos laços, e assim por diante…

Com o WordPress isso não é diferente, existem padrões de escrita para PHP, HTML, CSS e JavaScript, portanto, se você deseja começar a desenvolver temas e plugins, ou até mesmo se envolver com o projeto do CMS, deverá se educar para escrever seus códigos exatamente como os padrões de codificação WordPress exigem.

Neste artigo vamos tratar de todas as linguagens utilizadas no WordPress, tanto para desenvolvedores front-end quanto back-end.

PHP no WordPress

Como o WordPress é feito em PHP, desenvolvedores que sabem essa linguagem estão "em casa" quanto ao desenvolvimento, porém, é necessário seguir alguns princípios na hora de escrever seu código.

Veja abaixo.

Aspas simples e aspas duplas

Você deve utilizar aspas simples e duplas de maneira apropriada. Se não estiver avaliando nenhum valor, você deve utilizar aspas simples:

$string = 'Este é o meu valor!';

Caso contrário, é necessário utilizar aspas duplas:

$string = "O valor é $valor!";

Evite ao máximo escapar aspas com uma barra invertida, tenha em mente que isso faz seu código ficar difícil para ser lido e manipulado, além de feio.

Textos que vão em atributos HTML devem ser executados através de esc_attr(), que vai tratar os valores para evitar que aspas (ambas, as duplas e simples), sinal de maior que (>), sinal de menor que (<) e o "E" comercial (&), invalidem seu HTML.

Indentação

A indentação do seu código deverá ser feita sempre utilizando tabs, nunca espaços:

if ( 2 === $valor ) {
[tab]echo 'O valor é 2.';
[tab]echo 'Um mais um é 2.';
[tab]echo 'Quatro menos 2 é 2.';
}

Uma exceção seria quando você precisa alinhar os valores de um array para que o código fique mais bonito:

$array = array(
	'um'     => 1,
	'dois'   => 2,
	'três'   => 3,
	'quatro' => 4,
);

Um regrinha para não esquecer: Utilize tabs no início e espaços no meio das linhas para alinhamento.

Estilo das chaves

Todos os blocos (até os que não exigem) devem conter as chaves, exemplo:

if ( 1 === $valor ) {
	algumacoisa();
} else if ( 2 === $valor ) {
	algumacoisa();
	algumacoisa();
	algumacoisa();
} else {
	// Ação padrão
}

Se você tiver um bloco muito longo, considere dividi-lo em partes menores, ou em funções. Caso tenha realmente a necessidade de utilizar um bloco com mais de 35 linhas, faça um breve comentário na chave que fecha o bloco, para que qualquer desenvolvedor consiga identificar que aquela chave é daquele bloco, apenas lendo o final do mesmo.

// Verifica o valor
if ( 1 === $valor ) {
	/** 
	 *
	 * Meu bloco muito longo ...
	 *
	 **/
} // Verifica o valor

No demais, utilize sempre chaves em tudo que as requer:

if ( $condicao ) {
	acao();
}
 
if ( $condicao ) {
    acao();
} elseif ( $condicao ) {
    acao();
    acao();
}
 
foreach ( $itens as $item ) {
	processa_item( $item );
}

Expressões regulares

Expressões regulares compatíveis com o Perl (PCRE) devem ser utilizadas ao invés de POSIX. Nunca use o modificador /e, em vez disso, use preg_replace_callback.

short_open_tag: <? e ?>

Nunca, de maneira alguma, utilize as tags <? e ?>. Sempre utilize a tag do PHP completa <?php.

<?
$errado = "Nunca faça isso!";
?>

<?php
$agora_sim = 'Aqui está tudo correto!';
?>

Não deixe sobrar espaços no final

Normalmente, quando escrevemos códigos em PHP, costumamos fechar a última tag ?> do código, mesmo sabendo que ela não é necessária:

<?php
$agora_sim = 'Aqui está tudo correto!';

echo $agora_sim;

// Este código funciona e não deixa sobrar espaços no final

O trecho acima funciona mesmo sem a última tag do PHP, além disso, evita que sobrem espaços no final do nosso arquivo, o que não é permitido pelos padrões de codificação do WordPress.

Se o seu trecho terminar com a tag de fechamento do PHP, ou até em HTML, CSS ou Javascript, certifique-se de remover os espaços que sobrarem ao final da sua última linha de código. Se eles não são necessários, não há motivos para tê-los.

Uso de espaços

Você deve utilizar espaços depois de vírgulas e entre os parênteses:

$array = array( 1, 2, 3 );

Depois das chamadas dos laços e estruturas condicionais:

if[Espaço]( $condicao )[Espaço]{
	acao();
}

Exemplos:

if ( ... ) {
	...
}

foreach ( ... ) {
	...
}

while ( ... ) { 
	...
}

Para comparações, não coloque valores encostados nos operadores, exemplo:

if ( $x === $y && $y !=== $z ) {
	// Correto
}

Para concatenação, não coloque valores encostados no ponto (.):

$valor_1 = 'Valor 1 ';
$valor_2 = 'Valor 2 ';

// Correto
echo $valor_1 . $valor_2;

Para definir uma função, faça da seguinte maneira:

function funcao( $parametro_1 = 'valor 1', $parametro_2 = 'valor 2' ) {
    // Ação
}

Para chamar uma função, faça da seguinte maneira:

funcao( $parametro_1, func_param( $parametro_2 ) );

Para Type Casting, faça da seguinte maneira:

$numero = (integer) 10;
$foo = (boolean) $bar;

Para itens de um array, faça o seguinte:

<?php
$x = $foo['bar']; // correto
$x = $foo[ 'bar' ]; // incorreto
 
$x = $foo[0]; // correto
$x = $foo[ 0 ]; // incorreto
 
$x = $foo[ $bar ]; // correto
$x = $foo[$bar]; // incorreto

Convenções de nome

Sempre utilize letras minúsculas quando criar variáveis:

$variavel = 'Valor qualquer';

Para variáveis com nome composto, separe as palavras por um undeline (_):

$nome_da_variavel = 'Valor qualquer';

A mesma regra serve para funções:

function minha_funcao( $meu_parametro ) {
	...
}

Em caso de classes, utilize a primeira letra de cada palavra em maiúsculo. Se a palavra for um acrônimo, todas as letras devem ser maiúsculas:

class Walker_Category extends Walker { 
    ...
}

class WP_HTTP {
    ....
}

Os arquivos devem ser nomeados de maneira descritiva, com palavras separadas por um hífen:

nome-do-meu-plugin.php

Os arquivos das classes devem iniciar com a palavra class-, seguida do nome da classe com letras minúsculas. Exemplo:

class-wp-http.php

Arquivos contendo template tags dentro da pasta wp-includes, devem ter -templace ao final. Por exemplo:

general-template.php

Prefira argumentos autoexplicativos para funções

Se eu chamar a função abaixo:

comer('Arroz', true);

Apenas lendo o trecho acima você seria capaz de me dizer o que significam os dois parâmetros? Certo, comer (entendi o nome da função), 'Arroz' (beleza, comer arroz), mas e o segundo parâmetro? O que significa é o true.

Ao invés disso, eu poderia criar a minha função sem o uso desse booleano, o que traria muito mais sentido para quem fosse utilizar meu código, exemplo:

function comer( $comida = 'Arroz', $velocidade = 'Devagar' ) {
	... 
}

comer(); // Arroz, Devagar
comer('Feijão'); // Feijão, Devagar
comer('Churrasco', 'Rápido'); // Churrasco, Rápido

Isso facilita a vida de todo mundo.

Operador ternário

Sempre utilize o operador ternário para testar condições verdadeiras, nunca falsas. Por exemplo:

// (if condição verdadeira ) ? (faça isso) : (se não, faça isso);
$musica = ( 'rock' == $musica ) ? 'Legal' : 'Blah!';

Apenas teste uma condição falsa em caso de valores nulos e para verificar se variáveis estão setadas, exemplo:

if ( ! empty( $variavel ) ) {
	// A variável não está vazia
}

Mesmo assim, o trecho acima ainda causa uns 3 segundos de confusão na sua mente.

Yoda Conditions

Quando você está fazendo comparações, também está correndo um sério risco de esquecer o segundo sinal de igual, acabando por atribuir o valor comparado ao valor da variável, e fazendo a condição se tornar verdadeira. Veja um exemplo:

if ( $usuario = 'Admin' ) {
	// Pronto, agora a condição é verdadeira
	// e o usuário é o 'Admin'
}

Para evitar este problema, você pode utilizar este método, que consiste em inverter o valor comparado para a esquerda:

if ( 'Admin' === $usuario ) {
	// Agora sim
}

if ( true === $valor ) {
	// ...
}

No trecho acima, se você esquecer dos outros sinais de igual, pelo menos terá um erro:

Parse error: syntax error, unexpected '=' in local/do/arquivo.php on line N

É! Eu sei que seu código vai ficar meio estranho para ser lido, mas você acostuma.

Faça as coisas de maneira simples

Evite fazer as coisas de maneira complicada para outros desenvolvedores, veja:

$variavel = 'Um valor qualquer!';

isset( $variavel ) || $variavel = function() {
	return 'Muito importante!';
};

echo ! is_callable( $variavel ) ? $variavel : $variavel();

Mesmo que você seja um programador avançado, provavelmente vai levar alguns segundos para saber o que o trecho de código acima faz, e o pior, saber o porquê dele existir.

Seria muito mais simples se eu fizesse o seguinte:

if ( ! isset( $variavel ) ) {
	$variavel = function() {
		return 'Muito importante!';
	};
} else {
	$variavel = 'Um valor qualquer!';
}

echo is_callable( $variavel ) ? $variavel() : $variavel;

Pronto, agora o código está autoexplicativo: se a variável não estiver setada, ela é uma função; se já, ela tem um valor qualquer. Na exibição, eu apenas verifico se é uma função ou se é uma variável comum.

Documentação

Sempre documente seus arquivos, funções, classes e qualquer outra parte do seu código que você achar que deve ser comentada, pois, ninguém vai entender que aquela nova função que você criou, é para corrigir aquele bug que você encontrou ao executar o seu código. Às vezes, apenas um comentário simples, facilita a vida de qualquer desenvolvedor.

O WordPress utiliza um método de documentação padrão. Você pode encontrar mais detalhes sobre isso em:

  • PHP Documentation Standards

Basta uma lida rápida e já vai saber como documentar seu código.

Fonte: PHP Coding Standards

HTML no WordPress

Para os padrões de codificação HTML no WordPress, basta seguir o que a W3C recomenda. Por este motivo, você deve utilizar um validador HTML para avaliar o seu código.

As tags que são fechadas em si mesmas, como <br />, devem ter um único espaço antes da barra, por exemplo:

<br /> <!-- Correto -->
<br/> <!-- Incorreto -->

Você pode encontrar mais detalhes sobre isso no site da W3C.

Atributos e Tags

Todas as tags e atributos devem ser escritos com letra minúscula, veja:

<b>Negrito</b> <!-- Correto -->
<B>Negrito</B>  <!-- Incorreto -->

Os atributos que serão interpretados por máquinas, também devem ser escritos com letra minúscula. A exceção aqui é que apenas os atributos que vão ser lidos por humanos, podem ser escritos da maneira que você preferir. Veja outro exemplo:

Para máquinas

<meta http-equiv="content-type" content="text/html; charset=utf-8" />

Para humanos

<a href="http://exemplo.com/" title="Descrição Aqui">Exemplo.com</a>

Aspas

Todos os atributos devem estar entre aspas simples ou duplas, sem exceções:

<input type="text" name="email" disabled="disabled" /> <!-- Correto -->
<input type='text' name='email' disabled='disabled' /> <!-- Correto -->
<input type=text name=email disabled> <!-- Incorreto -->

Indentação

A indentação em HTML sempre deve refletir a estrutura do seu código utilizando tabs, não espaços.

Quando você estiver juntando PHP e HTML no seu arquivo, os trechos em PHP também devem ser indentados. Exemplo:

<?php if ( ! have_posts() ) : ?>
    <div id="post-1" class="post">
        <h1 class="entry-title">Not Found</h1>
        <div class="entry-content">
            <p>Apologies, but no results were found.</p>
            <?php get_search_form(); ?>
        </div>
    </div>
<?php endif; ?>

Fonte: HTML Coding Standards

CSS no WordPress

Crie um código que possa ser lido, que seja significativo, consistente e bonito.

  • Use tabs, não espaços, para recuar cada propriedade.
  • Adicione duas linhas em branco entre as seções e uma linha em branco entre blocos em uma seção.
  • Cada seletor deve estar em sua própria linha, que termina em uma vírgula ou uma chave. Pares de valor de uma propriedade devem estar em sua própria linha, com uma tab de recuo e um ponto e vírgula final. A chave de fechamento deve estar alinhada à esquerda, usando o mesmo nível de recuo do seletor de abertura.

Correto:

#seletor-1,
#seletor-2,
#seletor-3 {
    background: #fff;
    color: #000;
}

Incorreto:

#seletor-1, #seletor-2, #seletor-3 {
    background: #fff;
    color: #000;
    }
 
#seletor-1 { background: #fff; color: #000; }

Seletores

Tenha bom senso ao utilizar seletores, tente trabalhar corretamente com a especificidade do seu CSS.

/* Incorreto */
body div.classe {
	background: #fff;
}

/* Correto */
.classe {
	background: #fff;
}
  • Use letras minúsculas e palavras separadas por hifens ao nomear seletores. Evite camelcase e sublinhados.
  •  Use seletores legíveis que descrevem corretamente elemento
  • Seletores de atributo devem ter aspas em torno dos valores
  • Evite usar seletores super qualificados, div.container pode simplesmente ser declarado como .container

Veja exemplos do CSS correto e incorreto para o WordPress:

Correto

#comment-form {
    margin: 1em 0;
}
 
input[type="text"] {
    line-height: 1.1;
}

Incorreto

#commentForm { /* Não use camelcase. */
    margin: 0;
}
 
#comment_form { /* Não use underline. */
    margin: 0;
}
 
div#comment_form { /* Não super qualifique seletores. */
    margin: 0;
}
 
#c1-xr { /* O que é c1-xr?! Escolha um nome melhor. */
    margin: 0;
}
 
input[type=text] { /* Deveria ser [type="text"] */
    line-height: 100%
}

Propriedades

  • Propriedades devem ser seguidas por dois pontos e um espaço.
  • Todas as propriedades e valores devem estar em letras minúsculas, com exceção de nomes de fontes e propriedades específicas de cada desenvolvedor.
  • Use o código hexadecimal para cores, ou rgba() se opacidade for uma necessidade. Evite o formato RGB e letras maiúsculas nos hexadecimais. Encurte os valores quando possível: #fff, ao invés de #FFFFFF.
  • Use atalhos (exceto quando estiver substituindo estilos) para o background, border, font, list-style, margin, e valores de preenchimento, sempre que possível. (Para uma referência, consulte http://codex.wordpress.org/CSS_Shorthand).

Tente não ordenar suas propriedades e valores de maneira randômica, faça a ordenação dos valores de alguma forma que seja interessante para a semântica do seu arquivo.

Uma forma de ordenar as propriedades seria ordem alfabética, que é a mesma utilizada pela Automatic/WordPress.com. Veja um exemplo:

#overlay {
    background: #fff;
    color: #777;
    padding: 10px;
    position: absolute;
    z-index: 1;
}

Para propriedades TRBL (top, right, bottom e left), sempre utilize essa ordem. Exemplo:

.elemento-lindo {
	margin-top: 10px;
	margin-right: 15px;
	margin-bottom: 20px;
	margin-left: 2px;
}

Valores

Existem milhares de tipos de valores em CSS, portanto, siga as regras abaixo para manter a consistência no seu código:

  • Coloque um espaço antes do valor, depois dos dois pontos;
  • Não preencha parênteses com espaços;
  • Sempre termine com um ponto e vírgula;
  • Use aspas duplas ao invés de aspas simples, e apenas quando necessário, como quando um nome da fonte tem um espaço;
  • Valores zerados (0) não devem estar presentes e também não devem ter unidades, a menos que necessário, como no caso de transição de duração;
  • Altura de linha não deve ter unidade, a não ser que seja necessário definir um valor de pixel específico. Isso é mais do que apenas uma convenção estilo, mas vale a pena mencionar aqui. Mais informações em  http://meyerweb.com/eric/thoughts/2006/02/08/unitless-line-heights/;
  • Use um zero à esquerda para valores decimais, inclusive para rgba();
  • Vários valores separados por vírgulas para uma propriedade devem ser separados por um espaço ou uma nova linha, inclusive dentro de rgba(). Utilize novas linhas para valores muito longos.

Exemplo correto:

.class { 
    background-image: url(images/bg.png);
    font-family: "Helvetica Neue", sans-serif;
}
 
.class { 
    font-family: Georgia, serif;
    text-shadow: 0 -1px 0 rgba(0, 0, 0, 0.5),
                 0 1px 0 #fff;
}

Exemplo incorreto:

.class { /* Não esqueça do espaço */
    background:#fff
}
 
.class { /* Evite unidades em valores zerados */
    margin: 0px 0px 20px 0px;
}

Media queries

Media queries são excelentes para que configuremos vários estilos para um mesmo site em tamanhos de telas diferentes, porém, tente seguir as regras abaixo para manter consistência:

  • Agrupe todas as media queries no final do seu CSS;
  • Faça a indentação correta dentro das media queries.

Por exemplo:

@media all and (max-width: 699px) and (min-width: 520px) {
	body {
		background: #fff;
		font-size: 14px;
	}
}

Comentários

  • Comente, e comente sempre que achar necessário. Os comentários são excelentes para indicar o que você queria fazer com tal propriedade ou regra. Principalmente quando for para corrigir bugs para diferentes navegadores.
  • Para comentários muito longos, você deve manter no máximo 80 caracteres por linha;
  • Tente criar um índice de conteúdo (com números) para as sessões do seu CSS (1.0 ,1.1, 2.0…). Agrupe as regras para cada sessão;
  • Se quiser seguir um padrão, utilize o http://cssdoc.net (mas lembre-se que isso não é um requisito).

Exemplo de sessão:

/**
* #.# Título da sessão
*
* Descrição da sessão.
*/
 
.selector {
    float: left;
}

Exemplo de comentários em linha:

/* Este é um comentário sobre o seletor */
 
.another-selector {
    position: absolute;
    top: 0 !important; /* Eu devo explicar o motivo disso ser tão !important */
}

Fonte: CSS Coding Standards

Javascript no WordPress

Os princípios para JavaScript são basicamente os mesmos que você vai utilizar em PHP (veja no início do artigo), porém, como cada linguagem tem suas próprias necessidades, existem algumas diferenças.

Para encontrar maiores detalhes sobre os padrões de codificação JavaScript no WordPress, leia o artigo abaixo:

É bastante interessante que você mantenha consistência em todos os seus scripts e arquivos em HTML e CSS, tente seguir os mesmos princípios básicos descritos em todas as sessões desse artigo.

Comente, documente as partes do seu código, e, acima de tudo, tente escrever um código bonito e legível.

Concluindo

Bom código, é código legível.

Lembre-se que, quanto mais pessoas contribuírem com um código, mais desorganizado ele tende a ficar, porém, se você (e todo mundo) seguir as mesmas regras, tal código vai ficar organizado, como se uma só pessoa o tivesse escrito.

No mais, código bem documentado e bonito é mais fácil para ser mantido, mesmo que você trabalhe sozinho.

Em caso de dúvidas, não hesite em perguntar, afinal, a comunidade do WordPress é gigante, e sempre existe alguém disposto a ajudar.