Boas práticas que fazem a diferença #1 📝
Tags: braziliandevs, beginners, programming, productivity
Published: 2024-05-20 22:29:42

Esse é o primeiro post de uma série sobre boas práticas que eu aprendi durante a minha jornada, tanto no trabalho e processos seletivos, quanto na faculdade e projetos pessoais ou de comunidades.

## Sumário

- [1. Idioma](#1-idioma)  
- [2. Convenções](#2-conven%C3%A7%C3%B5es)  
  - [2.1. Nome de Arquivos](#21-nome-de-arquivos)  
  - [2.2. Nome de funções, variáveis e constantes](#22-nome-de-fun%C3%A7%C3%B5es-vari%C3%A1veis-e-constantes)  
  - [2.3. Commits](#23-commits)  
  - [2.4. Branches](#24-branches)  
- [3. Formatação](#3-formata%C3%A7%C3%A3o)  

## 1. Idioma

Muitas pessoas, principalmente iniciantes, não se atentam a esse ponto, e eu já ouvi das próprias pessoas recrutadoras sobre pessoas que infelizmente foram recusadas em processos seletivos por programaram os testes técnicos ou até mesmo só terem projetos pessoais públicos no GitHub em português ou misturando com o inglês.

Apesar de não haver uma regra, e no mercado variar muito de time para time, fica aqui algumas dicas:

1. Defina o(s) idioma(s) do seu projeto (código, commits, arquivos e documentação) de acordo com o seu público-alvo ou conhecimento;
2. Utilize inglês ou português no código, mas nunca misture os idiomas! Por exemplo: `getProduct` ou `retornarProduto`, mas evite misturar como `getProduto`.
3. Pergunte o idioma utilizado pelo time, isso vale principalmente em processos seletivos, muitas empresas nacionais fazem questões de utilizar o português, mas a grande maioria utiliza o inglês, além de poder lhe render pontos extras por se atentar a esses detalhes frequentemente ignorados.
4. Via de regra invista e use o inglês sempre que possível, mesmo porque as próprias linguagens de programação são escritas nele.

## 2. Convenções

Primeiramente, precisamos entender que uma convenção nada mais é do que qualquer padrão adotado, por preferências ou necessidades de uma **pessoa**, **time** ou **empresa**.

Existem também convenções diferentes dependendo da **área**, **stack**, ou **tecnologias** por si só, então vou dar exemplos baseada na documentação da tecnologia que eu mais utilizo no momento, o **Next.js**, mas aconselho fortemente a procurar a convenção mais adotada para a sua.

### 2.1. Nome de Arquivos

Tanto para pastas e arquivos é mais utilizado o `kebab-case`:

```
project-name/
├─ src/
│  ├─ app/
│  │  ├─ about-us/
│  │  │  ├─ page.module.css
│  │  │  ├─ page.tsx
│  │  ├─ page.module.css
│  │  ├─ page.tsx
│  ├─ components/
│  │  ├─ ui/
│  │  │  ├─ button.module.css
│  │  │  ├─ button.tsx
│  │  │  ├─ …
│  │  ├─ nav-bar.module.css
│  │  ├─ nav-bar.tsx
│  │  ├─ …
├─ …
```

### 2.2. Nome de funções, variáveis e constantes

O mais comum é você encontrar os nomes das funções, variáveis e constantes padronizados em `camelCase`, exceto para as funções de páginas em que no caso utilizamos `PascalCase`, e alguns casos de constantes em que utilizamos `SCREAMING_SNAKE_CASE`.

```tsx
async function getData() {
  const res = await fetch(process.env.API_URL)

  ...
}

export default function Page() {
  ...
}
```

### 2.3. Commits

Aqui nós podemos nos aprofundar muito, mas vamos manter simples por hoje.

O padrão mais comum pra os títulos dos commits é o tipo das mudanças seguido de uma breve descrição de forma imperativa e no futuro do presente delas. Já para a descrição, que é muito ignorada (confesso que até mesmo eu peco nisso), o ideal é descrever o porque daquela mudança proposta no commit, e o que de fato ela faz ou como deveria se comportar.

Exemplos:

```shell
git commit -m "feat: adiciona o botão de CTA"
```

- `feat: <descrição>` para novas funcionalidades;
- `fix: <descrição>` para correção de bugs;
- `chore: <descrição>` para alterações de configurações, dependências, etc.;
- `refactor: <descrição>` para re-fatoração de código;
- `docs: <descrição>` para alterações na documentação;
- `test: <descrição>` para alterações nos testes;
- `style: <descrição>` para alterações de estilos;
- `ci: <descrição>` para alterações no CI/CD;
- `perf: <descrição>` para alterações de performance;
- `revert: <descrição>` para reverter uma alteração;
- `merge: <descrição>` para merge de branches;
- `wip: <descrição>` para trabalhos em progresso;
- `release: <descrição>` para releases;
- `config: <descrição>` para configurações;
- `build: <descrição>` para build;
- `deploy: <descrição>` para deploy;
- `remove: <descrição>` para remoções;
- `add: <descrição>` para adições;
- `update: <descrição>` para atualizações.

### 2.4. Branches

Pretendo entrar em mais detalhes sobre o famoso Gitflow no próximo post, mas no geral, nós temos 3 branches principais: `main` sendo a principal, `hom` para homologação, `develop` para merge de outras branches, e em alguns casos até uma quarta chamada `stage`.

Similar aos commits, as branches derivadas da branch `develop`, nas quais nós de fato trabalhamos, frequentemente seguem o padrão de nome abaixo:

```shell
git branch develop feat/botão-de-cta
```

- `feature/<nome_da_funcionalidade>` para novas funcionalidades;
- `fix/<nome_da_correção>` para correção de bugs;
- `chore/<nome_da_alteração>` para alterações de configurações, dependências, etc.;
- `refactor/<nome_da_refatoração>` para re-fatoração de código;
- `docs/<nome_da_alteração>` para alterações na documentação;
- `test/<nome_do_teste>` para alterações nos testes;
- `style/<nome_do_estilo>` para alterações de estilos;
- `ci/<nome_da_alteração>` para alterações no CI/CD;
- `perf/<nome_da_melhoria>` para alterações de performance;
- `revert/<nome_da_alteração>` para reverter uma alteração;
- `merge/<nome_da_alteração>` para merge de branches.

### 3. Formatação

Tem se tornado cada vez mais comum a utilização de Linters e formatadores de código, com a intenção de prevenir erros, e padronizar a formação do código do projeto independente das preferências individuais do time.

Os mais comuns no frontend são o ESLint e Prettier, e em Python em suas diversas aplicações, temos ferramentas como o Black, Blue e o iSort.

---

Por hoje é isso, espero que gostem e para qualquer feedback ou discussão construtiva, nos vemos nas redes sociais e aqui nos comentários! 🎉