Diretrizes de programação para programadores do WP Staging

Se queres participar no desenvolvimento do WP Staging, familiariza-te com as seguintes diretrizes de programação e melhores práticas.

Usa PSR https://www.php-fig.org/psr/.
Usa sintaxe curta de Array [].
Usa camelCase para nomes de variáveis.
Usa StudlyCaps para nomes de classes.
Usa underscores em nomes de ficheiros e pastas.
Evita condições inline.
Usa abreviaturas raramente! Não uses qualquer abreviatura que não tenha sido aprovada pela equipa e não inventes as tuas próprias abreviaturas que não sejam comummente populares ao nomear propriedades ou métodos.
Nomes de classes, métodos e propriedades devem explicar exatamente o seu propósito.

Clean Code

O custo total de manter uma confusão vai-se acumulando com o tempo.
É muito difícil reconstruir um sistema legacy de raiz. Refatorar e fazer melhorias incrementais é frequentemente o melhor caminho.
Em codebases confusas pode demorar dias ou semanas a concluir tarefas que deviam demorar apenas horas.
Investe tempo para ires depressa.
Código limpo faz uma coisa bem feita. Código mau tenta fazer demasiado.
Código limpo está bem testado.
Quando lês código bem escrito, cada função faz praticamente o que esperavas.
Se discordas de um princípio que alguém com décadas de experiência está a ensinar, é boa ideia pelo menos considerar o ponto de vista dessa pessoa antes de o descartar.
Código é lido muito mais vezes do que é escrito.
Código mais fácil de ler é mais fácil de alterar.
Deixa a codebase melhor do que a encontraste (Boy Scout Rule).

Comentários e docBlocks

Os comentários podem mentir. Podem estar errados desde o início, ou podem começar por ser corretos e ficarem desatualizados ao longo do tempo conforme o código relacionado muda. Por exemplo: se renomeias ou refatoras um método, tens sempre de verificar se o comentário continua válido.
Usa comentários para descrever porquê algo está escrito daquela forma, não para explicar o que está a acontecer.
Os comentários podem frequentemente ser evitados usando variáveis com nomes claros e extraindo secções de código para funções com nomes claros.
Prefixa os teus comentários TODO de forma consistente para facilitar a pesquisa. Revisita e limpa os teus comentários TODO periodicamente.
Não uses docBlocks só por usar. Comentários que descrevem o que um método faz, que argumentos recebe e o que devolve são frequentemente, na melhor das hipóteses, redundantes e, na pior, enganadores.
Os comentários devem incluir toda a informação e contexto relevantes que quem lê o comentário vai precisar. Não sejas preguiçoso nem vago quando escreves um comentário.
Comentários de journal e de autor de ficheiro são desnecessários graças ao controlo de versões e ao git blame.
Não comentes código morto. Apaga-o. Se achas que vais precisar do código no futuro, é para isso que existe o controlo de versões.
Comenta o que for necessário, mas o mínimo possível. Se escreves o teu método e sentes uma forte pressão para escrever um comentário para ele, frequentemente o nome do teu método não é suficientemente claro ou o código faz mais do que uma coisa. Nesse caso, considera refatorar antes de escrever um comentário.

Estilo de código

Espaços em operadores binários

Os operadores binários ‘=’ e ‘=>’ devem estar rodeados por espaço. Há uma opção de autoformat nas definições de estilo de código do IDE que te permite alinhar atribuições key-value assim:

$array = [
    $var    => 'foo',
    $varvar => 'foo'
];

$var     = 1;
$var100  = 100;
$var2000 = 2000;

Este é um truque elegante para tornar maiores porções de código semelhante mais legíveis.

Yoda conditions

Votámos para não usar Yoda conditions para facilidade de leitura.

Não recomendado:

if ( true === $var ) {}

Recomendado:

if ( $var === true ) {}

Invocação nativa de funções/constantes

A invocação nativa é uma técnica para adicionar uma barra invertida (\) antes da invocação de funções/constantes para acelerar a resolução. Desta forma, o PHP não precisa de verificar se a função/constante é do namespace ou nativa.

Votámos para não usar a técnica de invocação nativa de funções/constantes para facilidade de leitura e evitar erros na nossa codebase.

Mas, em alguns casos, é permitido usar com cuidado e sabedoria.

Não recomendado:

if ( \is_array($var) ) {}
if ( \PHP_SAPI === 'cli') {}

Recomendado:

if ( is_array($var) ) {}
if ( PHP_SAPI === 'cli') {}

Namespaces e nomes de classes

De acordo com os princípios da Programação Orientada a Objetos (OOP), os nomes de classes devem ser substantivos, pois representam objetos ou conceitos no sistema. Isto ajuda a tornar o código mais legível e compreensível para outros programadores.

No entanto, vale a pena referir que algumas linguagens de programação, incluindo o PHP, permitem que verbos sejam usados como nomes de classes. Nestes casos, o verbo é geralmente usado como forma de indicar que a classe representa uma ação ou comportamento em vez de um objeto.

Por exemplo, uma classe chamada “Mailer” pode representar um objeto que envia emails, enquanto uma classe chamada “SendMail” pode representar um comportamento que envia emails. Embora seja tecnicamente permitido usar verbos como nomes de classes, isso pode tornar o código mais difícil de ler e perceber, e geralmente é desencorajado em favor do uso de substantivos.

Apenas os caracteres a-z, A-Z e 0-9 são permitidos para nomes de namespaces e classes.
Os namespaces são normalmente escritos em UpperCamelCase, mas são permitidas variações para nomes e abreviaturas bem estabelecidos.
Os nomes de classes são sempre escritos em UpperCamelCase.
O nome de classe não qualificado tem de ser literal mesmo sem o namespace.
O principal propósito dos namespaces é categorização e ordenação.
Os nomes de classes têm de ser substantivos, nunca adjetivos.
O nome de classes abstratas tem de começar com a palavra “Abstract”; nomes de classes de aspetos têm de terminar com a palavra “Aspect”.

Nomeação incorreta de namespaces e classes:

Nome completo da classe	Nome não qualificado	Observações
WPStaging\Framework\Session\Php	Php	A classe não é uma representação de PHP
WPStaging\Framework\Cache\Backend\File	File	A classe não representa um ficheiro!
WPStaging\Framework\Session\Interface	Interface	Não permitido, “Interface” é uma palavra-chave reservada
WPStaging\Framework\Controller\Default	Default	Não permitido, “Default” é uma palavra-chave reservada
WPStaging\Framework\Objects\Manager	Manager	Apenas “Manager” é demasiado vago

Nomeação correta de namespaces e classes:

Nome completo da classe	Nome não qualificado	Observações
WPStaging\Framework\Util\FileSystem	FileSystem	É o FileSystem
WPStaging\Framework\Cache\Backend\FileBackend	FileBackend	Um File Backend
WPStaging\Framework\Session\SessionInterface	SessionInterface	Interface para uma sessão
WPStaging\Framework\StandardController	StandardController	O controlador padrão
WPStaging\Framework\ObjectManager	ObjectManager

Casos limite na nomeação de namespaces e classes:

Nome completo da classe	Nome não qualificado	Observações
WPStaging\Framework\Mvc\ControllerInterface	ControllerInterface	Consequentemente, a interface pertence a todos os controladores no sub-namespace Controller
WPStaging\Framework\Mvc\Controller\ControllerInterface		Melhor
WPStaging\Framework\Cache\AbstractBackend	AbstractBackend	O mesmo aqui: na realidade esta classe pertence aos backends
WPStaging\Framework\Cache\Backend\AbstractBackend		Melhor

Métodos

Os nomes dos métodos devem descrever claramente o que fazem, por isso devem começar com um verbo como doSomething, makeSomething, isSomething, hasSomething.

Todos os nomes de métodos são escritos em lowerCamelCase. Para evitar problemas com diferentes sistemas de ficheiros, apenas os caracteres a-z, A-Z e 0-9 são permitidos para nomes de métodos — não uses caracteres especiais.

Faz os nomes de métodos descritivos, mas mantém-nos concisos ao mesmo tempo. Os construtores devem sempre chamar-se __construct(), nunca uses o nome da classe como nome de método.

myMethod()

someNiceMethodName()

betterWriteLongMethodNamesThanNamesNobodyUnderstands()

singYmcaLoudly()

__construct()

Propriedades e variáveis

Uma variável deve ser um substantivo ou adjetivo, nunca um verbo. Armazena algo e deve explicar o que contém.

Não uses a palavra-chave getSomething para uma propriedade. O get está reservado para getters e setters e para métodos que explicitamente fazem algo e onde não há melhor palavra-chave do que get.

Os nomes de variáveis são escritos em lowerCamelCase e devem ser:

Auto-explicativos.
Não encurtados além do reconhecível, antes mais longos se isso tornar o seu significado mais claro.

O exemplo seguinte mostra duas variáveis com o mesmo significado, mas com nomes diferentes. Vais certamente concordar que as versões mais longas são melhores (não vais…?).

Boa nomeação de variáveis

$singletonObjectsRegistry

$argumentsArray

$aLotOfHtmlCode

renderHTMLtoScreen

Má nomeação de variáveis

$sObjRgstry

$argArr

$cx

Como exceção especial, podes usar nomes de variáveis como $i, $j e $k para índices numéricos em ciclos for, se for claro o que significam à primeira vista. Mas mesmo nesses casos, deves tentar evitá-los.

i18n, sprintf(), esc_html_* e gettext()

Usa sempre primeiro as funções gettext() e envolve-as em sprintf() quando houver parâmetros numa string traduzível.

Errado:

esc_html_e(sprintf('There are %1$d monkeys in the %2$s'), $number, $string), 'text-domain');

Correto:

// Correct (multi-line):

sprintf(
	/* translators: number of monkeys, location. */
	__( 'There are %1$d monkeys in the %2$s', 'text-domain' ),
	(int) $number,
	esc_html( $string )
);

// Correct (single-line):

/* translators: number of monkeys, location. */
printf( __( 'There are %1$d monkeys in the %2$s', 'text-domain' ), intval( $number ), esc_html( $string ) );

Se usares printf ou sprintf, as aspas simples (‘) à volta da string são obrigatórias, porque as aspas duplas (“) indicam ao php para interpretar o $s como a variável s, o que não é o pretendido.

Para uniformizar com a ferramenta de tradução wporg, tem de incluir um placeholder para o tradutor.

/* translators: %s: name */
sprintf(esc_html__('string %s to translate', 'text-domain'), esc_html($string));

/* translators: %1$s = name1, %2$s = name2 */
sprintf(esc_html__('string %1$s to translate for %2$s', 'text-domain'), esc_html($string1), esc_html($string2));

Ler mais: https://developer.wordpress.org/plugins/internationalization/how-to-internationalize-your-plugin/#variables

Condições If Else

Evita condições inline se exigirem parênteses extra e instruções if-else, ou se tiverem mais do que vários estados a comparar.

Caso contrário, está tudo bem escrevê-las inline ou em condições separadas de early return.

Mau:

return ((!$this->isWindowsOs() && is_executable($fileName))) && is_writable($fileName) || ($this->isWindowsOs()) && is_writable($fileName);

Bom:

if (!$this->isWindowsOs && is_executeable && is_writeable()) {
     return true;
}

if ($this->isWindowsOs && is_writeable()) {
  return true;
}

return false;

Actions e Filters

Usa uma constante para declarar o nome do filtro; o nome da constante deve respeitar o padrão FILTER_*.
Começa sempre o nome de um filtro com wpstg, faz algum namespacing com pontos, como wpstg.backups.listing_table onde listing_table é o nome do método onde essa ação é usada.

Por exemplo:

// Declare const for filter
const FILTER_CLONING_UPDATE_ACTIVE_PLUGINS_FILTER = 'wpstg.cloning.update.active_plugins'

e depois

apply_filters(self::CLONING_UPDATE_ACTIVE_PLUGINS_FILTER, $activePlugins);

Guardar dados em wp_options

Usa uma constante para declarar o nome da opção; o nome da constante deve respeitar o padrão OPTION_*.
Começa sempre o nome de uma opção da tabela com wpstg, separa palavras com underscore como wpstg_backup_database_settings. Não te esqueças de adicionar a opção recém-adicionada ao uninstall.php