Boas práticas que fazem a diferença #1 📝

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
• 2. Convenções
  • 2.1. Nome de Arquivos
  • 2.2. Nome de funções, variáveis e constantes
  • 2.3. Commits
  • 2.4. Branches
• 3. Formatação

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.

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:

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:

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! 🎉