Guia de estilo de código
Published: 2024-02-08 21:26:23

## 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
}
```