Os padrões de codificação no desenvolvimento do WordPress são essenciais para uma base de código robusta e sustentável. Eles servem como diretrizes e convenções às quais os desenvolvedores aderem ao escrever códigos, ajudando a aprimorar a colaboração, simplificar a manutenção e garantir a confiabilidade geral.
Além disso, os padrões de codificação protegem você contra erros e armadilhas comuns, melhorando a qualidade do código. No desenvolvimento do WordPress, em que vários colaboradores frequentemente colaboram em um único projeto, os padrões de codificação sustentam o trabalho em equipe eficaz. Eles facilitam a comunicação, atenuam possíveis conflitos e contribuem para um processo de desenvolvimento mais eficiente.
A adesão aos padrões de codificação promove a consistência entre os projetos, facilitando para você alternar entre diferentes bases de código sem problemas. Essa consistência se estende à legibilidade e à capacidade de manutenção do código e promove um entendimento compartilhado entre os membros da equipe.
Os padrões oficiais de codificação do WordPress abrangem cinco áreas principais para que você tenha um processo de desenvolvimento coeso e eficiente:
- PHP para garantir a consistência do código no lado do servidor
- HTML para promover a marcação estruturada e semântica
- JavaScript para uma funcionalidade eficaz no lado do cliente
- CSS para manter uma abordagem de estilo consistente
- Acessibilidade para garantir que o produto final seja inclusivo e fácil de usar para pessoas com necessidades diversas
Neste artigo, exploramos esses padrões de codificação para ajudar você a começar a criar sites em conformidade e, talvez, contribuir para a comunidade de desenvolvimento do WordPress.
Padrões PHP no desenvolvimento do WordPress
Os padrões de codificação PHP específicos do WordPress garantem a consistência e a legibilidade do código do WordPress. Eles são obrigatórios para o WordPress Core e altamente recomendados para temas e plugins. Esses padrões abrangem vários aspectos, incluindo convenções de nomenclatura, indentação e estrutura de código para melhorar a legibilidade e facilitar a colaboração.
Os padrões PHP do WordPress abrangem as seguintes categorias:
- Geral – Esses padrões incluem colocar as tags PHP de abertura e fechamento em uma linha por si só ao incorporar um snippet PHP de várias linhas em um bloco HTML, evitar tags PHP abreviadas ao usar aspas simples e duplas e diretrizes para escrever declarações
include
erequire
:
// Opening and closing PHP tags within HTML:
// Put open/close tags on their own lines.
## DO
function foo() {
?>
<div>
<?php
echo esc_html (
bar (
$param1,
$param2
)
);
?>
</div>
<?php
}
## DON'T
if ( $x === $y ) { ?>
<div>
<?php }
// Avoid shorthand PHP tags
## DO
<?php ... ?>
<?php esc_html( $x ); ?>
## DON'T
<? ... ?>
<? esc_html( $x ); ?>
// Writing include/require statements:
// Avoid include_once as it continues execution
// even if the file is not found.
// Do not use brackets around the file path.
## DO
require_once ABSPATH . 'file-name.php'
## DON'T
require_once __DIR__ . '/file-name.php'
include_once ( ABSPATH . 'file-name.php' );
- Nomenclatura – Os padrões de nomenclatura incluem Convenções de Nomenclatura e interpolação para nomear hooks dinâmicos:
## DO
// Use lowercase letters for function and variable names.
function my_function( $some_variable ) {}
// Use uppercase letters for constant names.
define('MAX_AGE', 60);
## DON'T
// Use camelCase.
function myFunction( $someVariable ) {}
- Espaço em branco – Os padrões de espaço em branco definem diretrizes para o uso de espaço, indentação e remoção de espaços finais. (Se você quer iniciar um debate animado entre desenvolvedores, é só perguntar se eles preferem usar tabs ou espaços para indentar o código. Independentemente da sua preferência, a recomendação oficial para desenvolvedores de WordPress é usar tabs — e isso vale para JavaScript e CSS, além de PHP. Então, tenha isso em mente ao trabalhar em projetos colaborativos.)
## DO
// Put spaces after commas.
$colors = ['red', 'green', 'blue']
// Put spaces on both sides of the opening and
// closing brackets of control structures.
foreach( $foo as $bar ) { ...
// Defining a function:
function my_function() { ...
// Logical comparisons:
if ( ! $foo ) { ...
// Accessing array items:
$a = $foo['bar']
$a = $foo[ $bar ]
## DON'T
$colors = ['red','green','blue']
foreach($foo as $bar){ ...
function my_function(){ ...
if (!$foo) { ...
$a = $foo[ ‘bar’ ]
$a = $foo[$bar]
- Formatação – Os padrões de formatação para o desenvolvimento PHP no WordPress incluem estilos de chaves, declarações de arrays, diretrizes para chamadas de função multi-linha, declarações de tipo, constantes mágicas e o operador de espalhamento:
// DO
// Use the following brace style.
if ( condition ) {
action();
} elseif ( condition2 ) {
action2();
} else {
default_action();
}
// Declare arrays using the long syntax.
$numbers_long = array(1, 2, 3, 4, 5);
/* In multi-line function calls, each parameter should only take up one line.
Multi-line parameter values should be assigned a variable, and the variable passed to the function call. */
$data = array(
'user_name' => 'John Doe',
'email' => '[email protected]',
'address' => '123 Main Street, Cityville',
);
$greeting_message = sprintf(
/* translation function. %s maps to User's name */
__( 'Hello, %s!', 'yourtextdomain' ),
$data['user_name']
);
$result = some_function (
$data,
$greeting_message,
/* translation function %s maps to city name*/
sprintf( __( 'User resides in %s.' ), 'Cityville' )
);
// Magic constants should be uppercase.
// The ::class constant should be lowercase with no spaces around the scope resolution operator (::).
add_action( my_action, array( __CLASS__, my_method ) );
add_action( my_action, array( My_Class::class, my_method ) );
/* Add a space or new line with appropriate
indentation before a spread operator.
There should be:
* No space between the spread operator and the
variable/function it applies to.
* No space between the spread and the reference
operators when combined.
*/
//DO
function some_func( &...$arg1 ) {
bar( ...$arg2 );
bar(
array( ...$arg3 ),
...array_values( $array_vals )
);
}
//DONT
function some_func( & ... $arg1 ) {
bar(...
$arg2 );
bar(
array( ...$arg3 ),...array_values( $array_vals )
);
}
- Declarações “Declare”, namespace e importação – Esses padrões de codificação abrangem declarações de namespace e declarações
use
:
// Each namespace declaration should contain
// capitalized words separated by underscores.
namespace My_CompanyProjectKinsta_ProjectUtilities;
// Import use statements can use aliases
// to prevent name collisions.
use Project_NameFeatureClass_C as Aliased_Class_C;
- Programação orientada a objetos (OOP) – Esses padrões incluem o uso de apenas uma estrutura de objeto por arquivo, fornecendo diretrizes para o uso de declarações trait
use
, garantindo que a visibilidade seja sempre declarada, delineando a ordem da visibilidade e do modificador e apresentando uma visão geral das regras de instanciação de objetos:
// Trait use statements should be at the top of a class.
// Trait use should have at least one line before and after
// the first and last statements.
// Always declare visibility.
class Foo {
use Bar_Trait;
public $baz = true;
...
}
// Always use parentheses when instantiating a new
// object instance.
// Don't add space between a class name and the opening bracket.
$foo = new Foo();
-
- Estruturas de controle – As estruturas de controle incluem o uso de
elseif
, e nãoelse if
, e diretrizes para condições Yoda. Declarações Yoda: Ao misturar variáveis com constantes, literais ou chamadas de função em comparações lógicas, coloque a variável à direita para evitar a atribuição acidental, conforme mostrado abaixo:
- Estruturas de controle – As estruturas de controle incluem o uso de
// A "legal" comparison:
if ( true === $result ) {
// Do something with $result
}
// But a typo like this could get past you:
if ( $result = true ) {
// We will always end up here
}
- Operadores – Esses padrões abrangem operadores ternários, o operador de controle de erros (
@
) e operadores de incremento/decremento:
// Always have ternary operators
// test if the statement is true, not false.
$programming_language = ( 'PHP' === $language ) ? 'cool' : 'meh';
// Favor pre-increment/decrement over post-increment/decrement
// for stand-alone statements.
// DO
--$a;
// DON'T
$a--;
- Banco de dados – Os padrões de codificação de banco de dados fornecem instruções para a realização de consultas a bancos de dados e formatação de instruções SQL.
- Recomendações adicionais – As recomendações adicionais incluem padrões como o uso de valores de sinalização autoexplicativos para argumentos de funções, código inteligente, fechamentos (funções anônimas), expressões regulares, comandos de shell e instruções para evitar
extract()
.
Padrões de documentação inline do WordPress para código PHP
Além das diretrizes acima, o WordPress fornece padrões de documentação em linha para código PHP. O WordPress usa um esquema de documentação personalizado que se inspira na sintaxe do PHPDoc, um padrão em evolução para fornecer documentação ao código PHP mantido pelo phpDocumentor. Esses padrões simplificam a geração de documentação externa e contribuem para a comunidade mais ampla de desenvolvedores do WordPress, promovendo um entendimento compartilhado das estruturas da base de código.
A documentação do PHP no WordPress aparece principalmente como blocos formatados ou comentários em linha. Documente o seguinte nos arquivos do WordPress:
- Funções e métodos de classe
- Classes
- Membros da classe, incluindo propriedades e constantes
- Requerimentos e inclusões
- Hooks (ações e filtros)
- Comentários em linha
- Cabeçalhos de arquivos
- Constantes
Padrões HTML e CSS no WordPress
Os temas e plugins de WordPress seguem padrões rígidos de codificação HTML para garantir consistência, acessibilidade e facilidade de manutenção. As diretrizes enfatizam a marcação semântica, incentivando os desenvolvedores a usar elementos HTML para os fins pretendidos. Essa prática aprimora a estrutura do conteúdo e melhora o desempenho da otimização de mecanismos de pesquisa (SEO). Além disso, você é incentivado a validar seu HTML para garantir a compatibilidade entre os navegadores.
Os padrões de código HTML fornecem diretrizes para:
- Validação – Você deve validar todas as suas páginas HTML com o validador W3C para garantir que sua marcação esteja bem formada.
- Elementos de fechamento automático – A barra nos elementos de fechamento automático deve ter um espaço antes dela.
<!-- DO -->
<br />
<!-- DON'T –>
<br/>
- Atributos e tags – Todos os atributos e tags devem estar em letras minúsculas. Além disso, os valores de atributos só devem estar em minúsculas quando você estiver interpretando para máquinas. Se você estiver escrevendo para humanos, use a capitalização adequada para o título.
<!-- DO -->
<a href="http://example.com/" title="Link Description">Descriptive text</a>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<!-- DON'T -->
<a HREF="http://example.com/" TITLE="link description">Click here</a>
- Aspas – Todos os atributos devem ter um valor e devem usar aspas simples ou duplas. Se você não colocar aspas nos valores, poderá ter vulnerabilidades de segurança.
<!-- DO -->
<input type="text" name="email" disabled="disabled" />
<input type='text' name='email' disabled='disabled' />
<!-- DON'T -->
<input type=text name=email disabled>
- Indentação – A indentação do HTML deve sempre refletir a estrutura lógica. Ao misturar PHP e HTML, recue os blocos PHP para corresponderem ao código HTML ao redor.
<!-- DO -->
<?php if ( ! have_articles() ) : ?>
<div class="article">
<h1 class="article-title">Not Found</h1>
<div class="article-content">
<p>No results were found.</p>
<?php get_error_msg(); ?>
</div>
</div>
<?php endif; ?>
<!-- DON'T -->
<?php if ( ! have_articles() ) : ?>
<div class="article">
<h1 class="article-title">Not Found</h1>
<div class="article-content">
<p>No results were found.</p>
<?php get_error_msg(); ?>
</div>
</div>
<?php endif; ?>
Além desses padrões HTML, os padrões CSS do WordPress ajudam você a criar folhas de estilo limpas, modulares e responsivas. Eles definem uma linha de base para colaboração e revisão, desde o código principal até os temas e plugins. Essas diretrizes ajudam a garantir que seu código seja legível, consistente e significativo.
Os padrões de código CSS do WordPress enfatizam o uso de classes específicas para direcionar elementos, promovendo uma estrutura consistente e organizada. Especificamente, eles definem padrões para:
- Estrutura:
/* DO
Each selector should be on its own line ending with
a comma or curly brace. The closing brace should occupy
the same indentation level as the opening selector. */
#selector-1,
#selector-2 {
property: value;
}
- Seletores:
/* DO
Use lowercase and separate words using hyphens.
Use double quotes around values for attribute selectors.
Avoid overqualified selectors, such as div.container. */
#contact-form {
property: value;
}
input[type="text"] {
property: value;
}
- Propriedades (prefixos de pedido e fornecedor):
/* Append properties with a colon and a space.
Properties should be lowercase — except font names
snd vendor-specific properties — and use shorthand. */
#selector {
property: value;
}
- Valores:
/* Add a space before the value and a semicolon after.
Use double quotes.
0 values should not have units.
Use a leading zero for decimal values.
Delineate multiple comma-separated values for
a single property with a space or new line. */
#contact-form {
font-family: "Helvetica Neue", sans-serif;
opacity: 0.9;
box-shadow:
0 0 0 1px #5b9dd9,
0 0 2px 1px rgba(20, 120, 170, 0.9);
}
- Consultas de mídia:
/* Rules set for media queries should be indented one level in.
Keep media queries grouped by media at the bottom of the stylesheet. */
@media all and (max-width: 1024px) and (min-width: 780px) {
$selector {
property: value;
}
}
- Comentários:
Desde sua criação em 2003, os padrões de codificação do WordPress para HTML e CSS estão alinhados com as diretrizes do World Wide Web Consortium (W3C) para HTML e CSS. Enfatizando a integração de princípios de design responsivo e marcação semântica, os padrões do W3C influenciaram o desenvolvimento de temas e plugins, começando com o lançamento do HTML5 e do CSS3.
Essa adoção das diretrizes do W3C garante que os sites WordPress sigam os padrões globais da web, aprimorando a interoperabilidade e a experiência do usuário e refletindo o compromisso de se manter atualizado, seguro e compatível com o ecossistema mais amplo da web.
A adesão a essas diretrizes no WordPress enfatiza a verificação da qualidade do HTML com o validador de marcação HTML do W3C.
Esses padrões HTML e CSS garantem uma apresentação visualmente atraente, fácil de usar e eficiente dos sites WordPress em todas as plataformas. Eles oferecem suporte a uma experiência de usuário perfeita e facilitam a colaboração entre os desenvolvedores que trabalham em diversos aspectos do ecossistema do WordPress.
Padrões de codificação JavaScript no WordPress
Os padrões de codificação do WordPress também fornecem diretrizes para a formatação e o estilo do código JavaScript para temas e plugins. Além disso, esses padrões ajudam a promover a consistência do código juntamente com o código PHP, HTML e CSS principal.
Os padrões de codificação JavaScript do WordPress foram criados com base no Guia de estilo JavaScript do jQuery, que surgiu em 2012 como um conjunto abrangente de convenções de codificação que aprimora a consistência e a legibilidade do código. Inicialmente, ele atendia especificamente a projetos jQuery, mas seu sucesso levou a uma ampla adoção além da estrutura.
Embora as diretrizes do jQuery informem os padrões do WordPress, há algumas diferenças notáveis para o desenvolvimento do WordPress:
- O WordPress usa aspas simples para declarações de strings.
- As declarações de caso são recuadas nos blocos de switch.
- O conteúdo da função é recuado de forma consistente, incluindo os wrappers de fechamento de arquivo completo.
- Algumas regras de espaço em branco diferem para que você se alinhe aos padrões PHP do WordPress, como o uso de tabs ou indentação.
-
Os padrões de codificação JavaScript do WordPress abrangem as seguintes áreas:
- Refatoração de código.
- Espaçamento de código, incluindo declarações de objetos, arrays e chamadas de função:
// Object declarations
// DO
var obj = {
name: 'John',
age: 27,
height: 179
}
// DON'T
var obj = {
name: 'John', age: 27,
height: 179
}
// Arrays and function calls
// Include extra spaces around elements and arguments.
array = [ 1, 2 ];
foo( arg1, arg2 );
- Uso de ponto e vírgula:
// Always use semicolons
array = [ 1, 2 ];
- Indentação e quebras de linha, incluindo blocos e chaves, instruções de várias linhas e chamadas de métodos encadeados:
// Use tabs for indentation
( function ( $ ) {
// Expressions indented
function doSomething() {
// Expressions indented
}
} )( jQuery );
// if, else, for, while, and try blocks should span multiple lines
if ( condition ) {
// Expressions
} else if ( ( condition && condition ) || condition ) {
// Expressions
} else {
// Expressions
}
// Line breaks must occur after an operator if the statement
// is too long to fit on one line.
var html = '<p>The sum of ' + a + ' and ' + b + ' plus ' + c +
' is ' + ( a + b + c ) + '</p>';
/* If a chain of method calls is too long to fit on a single line,
use one call per line. The first call should be on a separate line from
the object on which the methods are called. */
elements
.addClass( 'foo' )
.children()
.html( 'hello' )
.end()
.appendTo( 'body' );
- Atribuições e globais, incluindo a declaração de variáveis com
const
elet
, a declaração de variáveis comvar
, globais e bibliotecas comuns. - Convenções de nomenclatura, como abreviações e acrônimos, definições de classe e constantes:
// Abbreviations must be written in camelCase.
// All letters of acronyms should be capitalized.
const userId = 1;
const currentDOMDocument = window.document;
// Class definition must use UpperCamelCaseConvention.
class Human {
...
}
// Constants should use SCREAMING_SNAKE_CASE convention.
const SESSION_DURATION = 60
- Igualdade:
// Use strict equality/inequality checks (=== and !==)
// instead of abstract checks (== and !=).
if ( name === "John" ) {
...
}
if ( result !== false ) {
...
}
// Also, with negation:
if !( result === false ) {
...
}
- Strings:
// Use single-quotes for string literals.
var myString = 'Hello world!'
- Declarações de troca:
// Use a break for each case other than default.
// Indent case statements one tab within the switch.
switch ( event.keyCode ) {
// ENTER and SPACE both trigger x()
case $.ui.keyCode.ENTER:
case $.ui.keyCode.SPACE:
x();
break;
case $.ui.keyCode.ESCAPE:
y();
break;
default:
z();
}
Além disso, os padrões de codificação do WordPress descrevem várias práticas recomendadas para você escrever código JavaScript.
Assim como no PHP, o WordPress fornece padrões de documentação em linha para o código JavaScript. Esses padrões em linha, que são blocos formatados de documentação ou comentários em linha, seguem o padrão JSDoc 3 para documentação em linha de JavaScript. Os padrões em linha abrangem funções, métodos de classe, objetos, fechamentos, propriedades de objetos, eventos e cabeçalhos de arquivos.
Como garantir a acessibilidade no desenvolvimento do WordPress
Os padrões de acessibilidade são cruciais para garantir que o conteúdo digital, incluindo sites criados em plataformas como o WordPress, possa ser usado por pessoas de todas as habilidades. Ao adotar os padrões de acessibilidade do W3C, você garante que os sites criados com o WordPress sejam inclusivos e acessíveis a pessoas com deficiências.
As diretrizes de acessibilidade da W3C, especificamente as Diretrizes de Acessibilidade para Conteúdo Web (WCAG), fornecem um quadro abrangente para tornar o conteúdo web mais acessível. Reconhecendo a importância da inclusividade, o WordPress incorporou essas diretrizes às suas funcionalidades principais.
Por exemplo, WCAG medem a conformidade com a Lei de Acessibilidade Europeia, que será aplicada a muitas organizações na UE a partir de junho de 2025.
Atender a diversas necessidades envolve a implementação de recursos e princípios de design, como compatibilidade com leitores de tela, navegação por teclado e alternativas de texto para conteúdo não textual.
Garantir a acessibilidade no WordPress não é apenas uma questão de conformidade. É um compromisso de fornecer a todos acesso igualitário a informações e serviços. Ao aderir às diretrizes da W3C, os Sites WordPress se tornam mais acessíveis e fáceis de usar, promovendo um ambiente on-line mais inclusivo.
Alguns exemplos práticos de implementação de recursos de acessibilidade em seus temas e plugins são os seguintes:
- Use HTML semântico – Garanta o uso adequado de tags HTML semânticas. Por exemplo, use
<nav>
para menus de navegação,<header>
para cabeçalhos de sites e<main>
para o conteúdo principal. Essas tags ajudam os leitores de tela e outras tecnologias de assistência a entender a estrutura da página. - Adicione alternativas de texto para conteúdo de imagens, vídeo e áudio – Forneça texto alternativo descritivo para imagens a fim de transmitir seu significado aos usuários que não podem vê-las. No WordPress, adicione atributos descritivos
alt
à biblioteca de mídia ao adicionar imagens. Inclua legendas e transcrições para vídeos e forneça alternativas de texto para o conteúdo de áudio para garantir que os usuários surdos ou com deficiência auditiva possam acessar as informações. - Crie com o design responsivo em mente – Certifique-se de que seu tema ou plugin seja responsivo e se adapte bem a diferentes tamanhos de tela. Essa abordagem beneficia os usuários com vários dispositivos e garante uma experiência consistente em todas as plataformas.
- Crie formulários acessíveis – Forneça etiquetas e instruções claros para os campos de formulário. Use os tipos de entrada apropriados, como e-mail ou telefone, para acionar o teclado correto em dispositivos móveis e tecnologias assistivas.
- Use a navegação por teclado – Certifique-se de que todos os elementos interativos possam ser navegados por meio de um teclado. Os usuários devem ser capazes de navegar por links, botões e campos de formulário. Teste e aprimore a acessibilidade do teclado, evitando a dependência de interações somente com o mouse.
Ferramentas para aderir aos padrões de codificação do WordPress
Há muitas ferramentas de detecção de código disponíveis que podem ajudar você a aderir aos padrões de codificação da plataforma descritos acima. Vamos analisar apenas algumas das ferramentas de validação que você pode usar para verificar os padrões de codificação do WordPress.
PHP_CodeSniffer
O PHP_CodeSniffer examina sua base de código PHP para identificar desvios das normas estabelecidas. Ele facilita um código mais limpo e eficiente, identificando infrações de codificação e discrepâncias de estilo. Isso leva a um melhor desempenho dos sites do WordPress e garante uma compatibilidade perfeita com futuras atualizações e plugins.
Serviço de validação de CSS da W3 Org
O serviço de validação de CSS da W3 Org examina as folhas de estilo CSS, identificando e corrigindo possíveis erros que possam impedir o desempenho ideal do site. Ele desempenha um papel fundamental na manutenção da consistência e da adesão aos padrões da W3C, garantindo uma experiência de usuário tranquila em vários dispositivos. Como resultado, os sites apresentam melhores tempos de carregamento e atendem aos rigorosos padrões de codificação CSS definidos pelo WordPress.
JSHint
O JSHint analisa o código JavaScript, identificando possíveis erros, inconsistências estilísticas e aderência às melhores práticas. Ele ajuda você a escrever um código mais limpo e eficiente, otimizando o desempenho do site. Seu foco atento nos padrões de codificação do WordPress garante que o código JavaScript se integre perfeitamente à arquitetura geral do WordPress, ajudando você a manter um ambiente de codificação coeso e padronizado.
WebAIM Contrast Checker
O Contrast Checker da WebAIM ajuda você a avaliar e melhorar a acessibilidade dos seus sites WordPress. Essa ferramenta simplifica o processo, muitas vezes complexo, de obter o contraste de cores ideal para promover a acessibilidade. Usando o feedback em tempo real do verificador de contraste, você pode identificar áreas para melhorar a legibilidade e a leitura do texto para todos os visitantes.
Resumo
Os padrões de codificação formam a base do desenvolvimento de software eficiente e colaborativo. Eles asseguram a consistência e a legibilidade do código, simplificam o processo de programação, melhoram a manutenção e facilitam o trabalho em equipe. Para os desenvolvedores do WordPress, seguir esses padrões é essencial para construir sites sólidos e escaláveis.
A Kinsta pode auxiliar você a atender a esses padrões, oferecendo suporte a ambientes de desenvolvimento que permitem que você se concentre em seu trabalho. Nossa própria suíte DevKinsta baseada em Docker permite que você projete e desenvolva sites WordPress em sua máquina local e, em seguida, implemente sem problemas em seus ambientes de produção. Combine o DevKinsta com nossa Hospedagem gerenciada de WordPress e você poderá passar mais tempo com seu código e menos tempo configurando servidores da web.
Deixe um comentário