Guia de estilo de código

Introdução

Este guia de estilo de código tem como objetivo estabelecer diretrizes para a escrita de código claro, legível e consistente nas aplicações desenvolvidas pelo time. Adotar práticas de estilo de código consistentes não só torna o código mais fácil de entender e manter, mas também promove a colaboração entre os desenvolvedores.

Para garantir que este documento permaneça relevante e útil ao longo do tempo, incentivamos a contribuição contínua de melhorias e sugestões. À medida que as tecnologias utilizadas em nossos projetos evoluem e novas práticas de desenvolvimento são adotadas, este guia será atualizado para refletir essas mudanças. Portanto, encorajamos os desenvolvedores a compartilhar suas experiências e insights para aprimorar este documento e ajudar a comunidade a escrever código de qualidade.

Laravel

Ferramentas de lint: Laravel Pint

Boas práticas:

• INDENTAÇÃO

Laravel: quatro espaços é a convenção padrão

// Evitar
if ($condition) {
  // código indentado com dois espaços
}

// Utilizar
if ($condition) {
    // código indentado com quatro espaços
}

Angular: dois espaços é a convenção padrão

// Evitar
if ($condition) {
    // código indentado com quatro espaços
}

// Utilizar
if ($condition) {
  // código indentado com quatro espaços
}

• QUEBRA DE LINHA

Legibilidade vs. Densidade de Informação: A quebra de linha em instruções longas ou arrays torna o código mais legível, facilitando a compreensão. Embora possa aumentar ligeiramente a densidade vertical do código, a melhoria na legibilidade geralmente supera essa preocupação.
Quebre linhas de código longas para melhorar a legibilidade.

Laravel:

// Evitar
return Response::json(['key' => 'value', 'another_key' => 'another_value']);

// Utilizar
return Response::json([
    'key' => 'value',
    'another_key' => 'another_value',
]);

// Evitar
$flights = Flight::where(‘active’, 1)->orderBy(‘name’)->take(10)->get();

// Utilizar
$flights = Flight::where(‘active’, 1)
    ->orderBy(‘name’)
    ->take(10)
    ->get();

Angular:

// Evitar
<div toggle #firstToggle="toggle" (toggle)="onToggle('first', $event)" [ngClass]="{ 'active': isActive }" [ngStyle]="{ 'color': isActive ? 'blue' : 'red' }" *ngIf="isVisible">

// Utilizar
<div toggle 
  #firstToggle="toggle" 
  (toggle)="onToggle('first', $event)"
  [ngClass]="{ 'active': isActive }"
  [ngStyle]="{ 'color': isActive ? 'blue' : 'red' }"
  *ngIf="isVisible"
>

• CHAVES

Consistência vs. Economia de Espaço: Usar chaves mesmo em blocos de código com uma única instrução promove a consistência e clareza. Embora possa parecer redundante em casos simples, ajuda a evitar erros quando mais instruções são adicionadas ao bloco no futuro.

Métodos e Funções: Inicie as chaves na linha seguinte após a declaração do método ou função.

// Evitar
public function exemplo(){
    // código
}

// Utilizar
public function exemplo()
{
    // código
}

Classes: Inicie as chaves na mesma linha a seguir à declaração da classe.

// Evitar
class Exemplo {
    // código
}

// Utilizar
class Exemplo 
{
    // código
}

Estruturas de Controle (if, else, for, foreach, while, switch, etc.): Inicie as chaves na mesma linha da declaração da estrutura de controle.

// Evitar
if ($condition) 
{
    // código
} else 
{
    // código
}

// Utilizar
if ($condition) {
    // código
} else {
    // código
}

• OPERADOR TERNÁRIO

Clareza vs. Complexidade: O operador ternário é útil para expressões simples e curtas, mas pode comprometer a clareza em expressões mais complexas ou quando aninhados. Use-o com moderação e opte por clareza sobre concisão quando a lógica se tornar obscura.

Laravel:

// Evitar
$result = ($status === 'ativo') 
    ? ($role === 'admin'
        ? 'Usuário ativo com papel de administrador' 
        : 'Usuário ativo comum') 
    : 'Usuário inativo';

// Utilizar
$message = ($status === 'ativo') 
    ? 'Usuário ativo' 
    : 'Usuário inativo';

Angular:

// Evitar
result = (status === 'ativo') 
    ? (role === 'admin'
        ? 'Usuário ativo com papel de administrador' 
        : 'Usuário ativo comum') 
    : 'Usuário inativo';

// Utilizar
message = (status === 'ativo') 
    ? 'Usuário ativo' 
    : 'Usuário inativo';

• COMENTÁRIOS

Compreensão vs. Poluição do Código: O código deve ser claro o suficiente para dispensar comentários, portanto quando necessário fazer comentários, priorize comentar o porquê ao invés de o que o código faz.

Comentário Ruim (Focando no "O Quê"):

// Calcula o desconto do cliente com base no tipo de cliente e histórico de compras.
const discount = calculateDiscount(customerType, purchaseHistory);

Comentário Bom (Explicando a Decisão de Design):

// Usando um array para armazenar os dados porque precisamos preservar a ordem dos itens.
const data = [item1, item2, item3];

• ANNOTATIONS (php)

Documentação Completa vs. Concisa: Métodos públicos devem ser documentados com annotations para garantir informações importantes sobre como usar esses métodos, incluindo detalhes sobre seus parâmetros, tipo de retorno e possíveis exceções lançadas.

/**
 * Envia um e-mail de confirmação para o usuário.
 *
 * @param User $user O usuário para o qual enviar o e-mail.
 * @return void
 */
public function sendConfirmationEmail(User $user)
{
    // lógica para enviar e-mail de confirmação
}

• NOMENCLATURAS

Métodos e Funções:
Use verbos no infinitivo para descrever a ação realizada pelo método ou função. Exemplo: calcularTotal(), salvarUsuario().
Escolha nomes descritivos que indiquem claramente a finalidade ou o resultado esperado da ação.

Classes:
Use substantivos ou frases nominais para nomear classes. Exemplo: UsuarioController, PedidoService.
Utilize o padrão PascalCase para nomes de classes, ou seja, inicie cada palavra com letra maiúscula e sem espaços entre as palavras.

Variáveis:
Use nomes significativos e descritivos para variáveis.
Evite abreviações obscuras ou nomes pouco claros.
Prefira camelCase para nomes de variáveis, ou seja, inicie com letra minúscula e inicie cada palavra subsequente com letra maiúscula.

// Evitar
$a = $request->someInput;
$nome_variavel = 'Valor da variável';

// Utilizar
$someInput = $request->someInput;
$nomeVariavel = 'Valor da variável';

Constantes:
Constantes dentro de uma classe deve ser declarado com todas as letras maiúsculas separado por underlines para nomes compostos:

const EMPRESA = 'Senai';
const TIPO_PRODUTO = 'Curso';

Angular

• INDENTAÇÃO Espaços em Branco vs. Tabs: Na comunidade Angular, é comum utilizar dois espaços para indentação. Isso ajuda a manter a consistência e legibilidade do código em todo o projeto, facilitando a colaboração entre os desenvolvedores.

// Evitar
if (condition) {
    // código indentado com quatro espaços
}

// Utilizar
if (condition) {
  // código indentado com dois espaços
}

• QUEBRA DE LINHA

Legibilidade vs. Densidade de Informação: quebrar linhas em instruções longas ou arrays melhora a legibilidade. Dividir o código em várias linhas torna cada parte mais clara e compreensível, facilitando a manutenção. Apesar de aumentar a densidade vertical, a legibilidade compensa, resultando em um código mais claro e fácil de entender

// Evitar
if (condition && anotherCondition && someOtherCondition && lastCondition) {
  // Código executado se todas as condições forem verdadeiras
}

// Utilizar
if (condition
    && anotherCondition
    && someOtherCondition
    && lastCondition
) {
  // Código executado se todas as condições forem verdadeiras
}