Workflow

Guia de Boas Práticas de Codificação

Este documento tem como objetivo fornecer um conjunto de diretrizes e práticas recomendadas para o desenvolvimento de software. Seguir estas práticas não só melhora a qualidade do código, mas também facilita a manutenção, a colaboração entre desenvolvedores e a escalabilidade dos projetos.

Legibilidade

• Nomeação Significativa: Use nomes claros e descritivos para variáveis, funções, classes e outros identificadores. Evite abreviações obscuras. Nomes devem refletir a intenção e o uso.
• Consistência de Estilo: Adote e siga um guia de estilo consistente. Isso inclui convenções sobre indentação, uso de chaves, espaçamento e nomenclatura.
• Comentários e Documentação: Comente seu código onde necessário para explicar "por que" algo está sendo feito. Mantenha a documentação atualizada, especialmente para APIs públicas.

Simplicidade

• Mantenha Simples: Escreva código simples e evite complexidade desnecessária. Prefira soluções claras e concisas.
• Refatore quando necessário: Não hesite em refatorar o código para simplificar ou melhorar a clareza. Código limpo e bem organizado é mais fácil de manter e entender.
• Princípio KISS (Keep It Simple, Stupid): Evite soluções complicadas. Uma solução mais simples é geralmente melhor do que uma complexa.
• Princípio DRY (Don't Repeat Yourself): Evite a repetição de informações ou lógica. Crie funções, classes ou módulos reutilizáveis para evitar redundância

Eficiência

• Otimização Prematura: Evite otimizar o código prematuramente. Primeiro, faça funcionar corretamente, depois otimize por desempenho onde os testes mostrarem que é necessário.
• Recursos e Gerenciamento de Memória: Seja consciente do uso de recursos e gerenciamento de memória, especialmente em ambientes com recursos limitados.

Segurança

• Práticas de Codificação Segura: Siga as práticas recomendadas para evitar vulnerabilidades comuns, como injeções SQL, cross-site scripting (XSS) e outros ataques.
• Dados Sensíveis: Trate dados sensíveis com cuidado, utilizando criptografia quando necessário e seguindo as políticas de privacidade e proteção de dados.

Testabilidade

• Escreva Código Testável: Desenvolva com a testabilidade em mente. Isso inclui a adoção de princípios como SOLID e a separação de preocupações para facilitar a escrita de testes.
• Cobertura de Testes: Mantenha uma cobertura de testes adequada para o seu código. Testes unitários, de integração e end-to-end são importantes para garantir a qualidade e a funcionalidade do software.

Manutenção

• Controle de Versão: Use sistemas de controle de versão, como Git, para gerenciar mudanças no código. Mantenha um histórico limpo com mensagens de commit claras.
• Dependências: Gerencie cuidadosamente as dependências do projeto para evitar conflitos e problemas de segurança. Mantenha as dependências atualizadas.

Colaboração

• Revisões de Código: Pratique revisões de código como parte do processo de desenvolvimento. Revisões ajudam a identificar problemas cedo e promovem a partilha de conhecimento.
• Paridade de Conhecimento: Encoraje a partilha de conhecimento entre a equipe. Evite o problema do "único ponto de falha" onde apenas uma pessoa entende parte do sistema.

Seguir estas práticas de codificação não apenas melhora a qualidade do código, mas também facilita a colaboração em equipe, a manutenção do projeto e contribui para a entrega de software de alta qualidade.

Fluxo de trabalho colaborativo

O fluxo de trabalho com Git opera através de duas branches principais: develop e main, que duram para sempre, e duas branches de suporte temporárias, feature e hotfix, que permanecem ativas até serem mescladas com as branches principais.

Branch Master/Main

Esta é a branch principal do projeto, onde reside o código de produção estável. Todas as alterações que estão prontas para serem lançadas em produção são mescladas nesta branch.
As formas de interagir com essa branch são através de Hotfixes ou merges da Develop.

Branch Develop

A branch de desenvolvimento, onde o trabalho diário ocorre. Ela reflete a versão mais atualizada do código e é a base para todas as novas funcionalidades. As alterações são mescladas aqui antes de serem promovidas para a branch principal.

Branch Staging

Esta é uma branch intermediária entre a branch de desenvolvimento e a produção. Ela utiliza o ambiente de produção, porém em uma URL diferente, funcionando como um preview das alterações antes de serem lançadas oficialmente. As alterações que estão prontas para serem testadas pelo cliente ou revisadas internamente são mescladas nesta branch. É importante garantir que as alterações nesta branch estejam completamente testadas e prontas para serem promovidas para a branch principal de produção.

Branch Feature

Essas branches são usadas para o desenvolvimento de funcionalidades específicas. É recomendável seguir uma convenção de nomeação, como iniciar o nome da branch com feature, por exemplo, feature/[id-do-card].

É crucial notar que as branches de features são criadas a partir da branch Develop e são removidas após o merge com a branch Develop. Se tivermos dez funcionalidades a serem desenvolvidas, criaremos dez branches independentes.

É importante salientar que as branches de features não podem ter interação com a branch Master, apenas com a branch Develop.

Branch Hotfix

Criadas a partir da branch main, as branches de hotfix são utilizadas para corrigir problemas críticos no código de produção. Uma vez concluídas, as correções são mescladas tanto na main quanto na develop para garantir que as correções sejam aplicadas em ambos os ambientes.

Processo de Merge

Abrindo Pull Requests

Para manter um histórico de fácil consulta, as Pull Requests devem ser abertas no GitHub.
O desenvolvedor responsável pela feature ou hotfix é encarregado de abrir a Pull Request.

Aprovação e Merge para Develop

O próprio desenvolvedor que abre a Pull Request pode revisar, aprovar e realizar o merge para a branch Develop assim que a implementação estiver pronta.
Isso agiliza o processo e garante uma integração contínua na branch de desenvolvimento.

Validação para Produção

As Pull Requests da branch Develop para a branch Master exigem a validação de outro desenvolvedor do projeto. Este segundo desenvolvedor revisa o código, testa a funcionalidade e, se tudo estiver correto, aprova a Pull Request para que a atualização seja mesclada na branch Master.
Isso assegura uma camada adicional de revisão antes da liberação para produção.

Feature Flags

Feature Flag ou em tradução livre, alternância de recursos, é uma técnica que permite, dentre outras coisas: que seja possível ativar ou desativar uma funcionalidade em produção em tempo real sem fazer deploy, além de disponibilizar uma funcionalidade para uma parte dos seus clientes para fazer experimentação; desativar uma funcionalidade, sem precisar fazer rollback do código (o que exigiria outro deploy da aplicação); ativar uma feature somente para testes, definindo quem vai ver a feature (que podemos escolher somente um dev, por exemplo); permite que a pessoa QA (Quality Assurance ou analista de qualidade) faça testes na aplicação com a funcionalidade habilitada e desabilitada; e, por fim, facilita a remoção de funcionalidades que ninguém mais usa no seu sistema.

Convenção de Commits

O Conventional Commits é uma convenção simples de mensagens de commit, que segue um conjunto de regras e que ajuda os projetos a terem um histórico de commit explícito e bem estruturado.

• Formato: <type>(<scope>): <subject>
  • <scope> é opcional

Exemplo:

feat: add hat wobble
^--^  ^------------^
|     |
|     +-> Summary in present tense.
|
+-------> Type: chore, docs, feat, fix, refactor, style, or test.

Tipo e Descrição:

• feat: Indicam que seu trecho de código está incluindo um novo recurso para o usuário.
• fix: Indicam que seu trecho de código está solucionando um problema para o usuário.
• docs: Indicam que houve mudanças na documentação, como por exemplo no Readme do seu repositório. (Não inclui alterações em código)
• style: Indicam que houve alterações referentes a formatações de código, semicolons, trailing spaces, lint... (Não inclui alterações em código).
• refactor: Referem-se a mudanças devido a refatorações que não alterem sua funcionalidade, como por exemplo, uma alteração no formato como é processada determinada parte da tela, mas que manteve a funcionalidade, ou melhorias de devido a um code review.
• test: São utilizados quando são realizadas alterações em testes, seja criando, alterando ou excluindo testes unitários. (Não inclui alterações em código)
• chore: Indicam atualizações de tarefas de build, configurações de administrador, pacotes... como por exemplo adicionar um pacote no gitignore. (Não inclui alterações em código)
• perf: Indicam que houve alterações de código que estejam relacionadas a performance.
• ci: Indicam mudanças relacionadas a integração contínua. (Continuous integration)
• wip: Indicam mudanças em andamento.

Padronização de URLs em APIs

• URLs devem ser fáceis de entender e interpretar.
• Manter uma estrutura uniforme para facilitar o desenvolvimento e a manutenção.
• Evitar vulnerabilidades e ambiguidades na definição de endpoints.
• Prever possíveis expansões sem quebrar versões existentes da API.
• Evite o uso de letras maiúsculas nas URLs para garantir consistência.
• Não inclua informações sensíveis ou complexas diretamente na URL
• Utilize o corpo da requisição para dados mais extensos.
• Mantenha URLs curtas e intuitivas.

Verbos HTTP

Os verbos HTTP indicam a ação a ser realizada sobre o recurso.
Utilize os seguintes verbos de acordo com a operação desejada:

• GET: Recuperar informações.
• POST: Criar um novo recurso.
• PUT/PATCH: Atualizar um recurso existente.
• DELETE: Remover um recurso.

Exemplo:

GET https://api.example.com/v1/users
POST https://api.example.com/v1/users
PUT https://api.example.com/v1/users/{userId}
PATCH https://api.example.com/v1/users/{userId}
DELETE https://api.example.com/v1/users/{userId}

Nomes de Recursos

Os nomes de recursos devem ser representados no plural e em kebab-case para coleções.

Exemplo:

+ Correto:
 
+ GET https://api.example.com/v1/users
+ GET https://api.example.com/v1/users/{userId}
+ GET https://api.example.com/v1/users/{userId}/permissions
+ GET https://api.example.com/v1/users/{userId}/permissions/{permissionId}

- Incorreto:
 
- GET https://api.example.com/v1/user
- GET https://api.example.com/v1/user/{userId}
- GET https://api.example.com/v1/usersPermissions/{userId}
- GET https://api.example.com/v1/users/{userId}/userPermission/{permissionId}

Padronização do uso de Prefixos: "on" e "handle"

O prefixo "on" é usado para criar diretivas que chamam métodos quando uma ação específica ocorre, mas não está relacionada à interação do usuário. Essas ações podem estar relacionadas a mudanças de estado, atualizações de dados ou resultados de operações.

Por outro lado, o prefixo "handle" é usado para criar métodos que tratam de eventos disparados pelo usuário, como submissões de formulários, cliques em botões e outros controles interativos.

Exemplos de uso do prefixo "on"

• onContentLoaded() - chamado quando o conteúdo é carregado
• onDataUpdated() - chamado quando os dados são atualizados
• onErrorOccurred() - chamado quando um erro ocorre

Esses exemplos demonstram como o prefixo "on" pode ser usado para criar diretivas que respondem a mudanças de estado ou dados.

Exemplos de uso do prefixo "handle"

• handleSubmit() - chamado quando o usuário submete um formulário
• handleClick() - chamado quando o usuário clica em um botão
• handleScroll() - chamado quando o usuário rola a página

Esses exemplos ilustram como o prefixo "handle" pode ser usado para criar métodos que respondem à interação do usuário, como submissões de formulários ou cliques em botões.

Extensões Essenciais e Opcionais do VSCode

Extensões essenciais e opcionais para o Visual Studio Code (VSCode) que aprimoram sua experiência de desenvolvimento. Essas extensões oferecem funcionalidades que melhoram a edição de código, formatação, linting e a eficiência geral do fluxo de trabalho.

Extensões Obrigatórias

1. Angular Language Service (Angular.ng-template (opens in a new tab)):
   Fornece recursos de edição inteligentes específicos para templates Angular, incluindo destaque de sintaxe, autocompletar código e verificação de erros.

2. EditorConfig for VS Code (EditorConfig.EditorConfig (opens in a new tab)):
   Permite estilos de codificação consistentes em diferentes editores, integrando-se com arquivos EditorConfig.

3. ESLint (dbaeumer.vscode-eslint (opens in a new tab)):
   Integra o ESLint, um linter JavaScript popular, no VSCode. O ESLint ajuda a identificar e corrigir erros de codificação e inconsistências estilísticas.

4. Prettier - Code formatter (esbenp.prettier-vscode (opens in a new tab)):
   Formata seu código automaticamente com base nas regras do Prettier, garantindo formatação e legibilidade consistentes.

5. Tailwind CSS IntelliSense (bradlc.vscode-tailwindcss (opens in a new tab)):
   Fornece autocompletar de código inteligente e outras funcionalidades específicas para Tailwind CSS, um framework CSS de primeira utilidade.

Extensões Opcionais

1. Pretty TypeScript Errors (YoavBls.pretty-ts-errors (opens in a new tab)):
   Torna os erros do TypeScript mais bonitos e legíveis no VSCode.

2. Template String Converter (meganrogge.template-string-converter (opens in a new tab)):
   Converte uma string em uma template string quando ${ é digitado.

As extensões obrigatórias são consideradas essenciais para um fluxo de trabalho de desenvolvimento tranquilo e eficiente em diversos cenários de codificação. Instalá-las melhorará significativamente a edição de código, manterá a formatação consistente, identificará problemas de codificação e otimizará seu processo de desenvolvimento.

As extensões opcionais oferecem conveniência e melhoram a experiência de codificação, mas não são obrigatórias para a funcionalidade básica de desenvolvimento. A escolha de instalá-las dependerá de suas necessidades e preferências específicas.