| Área | Stack |
|---|---|
| Frontend |              |
| Backend |                |
| Mobile |     |
| Banco de dados |         |
| Bots & Integrações |      |
| Padrões |       |
Olá Dev! Neste projeto documento meu code style (estilo de código) e o meu setup (as configurações que uso). Aqui estão as convenções, os padrões e as boas práticas que sigo no dia a dia.
Note
Este guia reflete o que pratico hoje, e continua mudando. Dependendo do contexto, outros princípios entram ou se sobrepõem aos daqui: o tipo de projeto, a cultura da empresa, o acordo com os outros profissionais do time. O entendimento coletivo sempre prevalece.
Cada conceito vem com exemplo. É a ideia do learn by example (aprender pelo exemplo): a regra escrita explica, e o código ao lado mostra.
Penso como um resolvedor de problemas, e procuro aplicar as boas práticas como um sênior faria. Na prática, isso quer dizer olhar o ciclo de vida inteiro do software: o código que entra hoje vai ser lido, alterado e operado por alguém durante anos.
O código serve ao time, e a governança acompanha o ciclo todo. Mostrar a complexidade em camadas faz com que todo mundo entenda o que está acontecendo, do não técnico ao especialista. Quem entende o sistema consegue propor ideia nova e melhoria.
Confira os detalhes em Governança.
Os fundamentos daqui valem em qualquer linguagem. Escolhi JavaScript para ilustrar, porque é a linguagem que mais gente lê sem precisar de tradução, e os mesmos princípios se aplicam a qualquer stack (o conjunto de tecnologias de um projeto).
Note
Em time, a melhor abordagem é sempre a convenção que a organização já definiu.
Todo princípio daqui pode ser aplicado em qualquer linguagem.
Estão organizados como um checklist de revisão, do mais amplo ao mais detalhado:
- Forma: avalia a estrutura da função de fora para dentro
- Legibilidade: analisa fluxo, espaçamento e nomes, linha a linha
- Controle de qualidade: confere estado, erros, código assíncrono e testes
Ver todos os princípios
Forma: estrutura e narrativa da função
| Princípio | Descrição |
|---|---|
| Escrita em inglês | Código universal, com nomes curtos e sem ambiguidade |
| Código narrativo | O código explica sozinho o que faz, e dispensa o comentário |
| Ponto de entrada limpo | A chamada de uma linha diz o que acontece, e os detalhes ficam abaixo |
| Estilo vertical | Até 3 parâmetros na linha. Com 4 ou mais, use um objeto |
| Orquestrador no topo | A chamada aparece antes das funções que fazem o trabalho |
| Detalhes abaixo | As funções auxiliares ficam abaixo do orquestrador que as chama |
| Sem lógica no retorno | O return nomeia o resultado que a linha anterior calculou |
Legibilidade: fluxo, densidade visual e nomes
| Princípio | Descrição |
|---|---|
| Retorno antecipado | Sai cedo na falha, e dispensa o else depois do return |
| Fluxo linear | O aninhamento em cascata dá lugar a um fluxo plano |
| Baixa densidade visual | Linhas relacionadas ficam juntas, e uma linha em branco separa os grupos |
| Nomes expressivos | A variável e a função dizem o que são, e dispensam explicação |
| Código como documentação | O nome expressivo dispensa o comentário, que fica desatualizado quando o código muda |
| Sem valores mágicos | Constante nomeada no lugar do número e da string soltos |
Controle de qualidade: estado, erros, código assíncrono e testes
| Princípio | Descrição |
|---|---|
| Funções pequenas | Uma responsabilidade, em um nível de abstração |
| Cálculo separado da formatação | Uma função calcula o dado, e outra o formata para exibir |
const como padrão |
O valor não muda depois de atribuído. O let entra quando ele precisar mudar |
| CQS | Comando e consulta em funções separadas, sem efeito colateral escondido |
| Dependências explícitas | A dependência entra por parâmetro, e o estado global fica de fora |
| Falhar rápido | Valida na entrada, e interrompe o fluxo inválido ali mesmo |
| Retorno explícito | A exceção sinaliza o inesperado. O fluxo normal segue pelo retorno |
| Contratos consistentes | A resposta sai sempre no mesmo formato |
| Tratamento centralizado de erros | Classes de erro tipadas, com o try/catch nos limites do sistema |
| Entrada e saída assíncronas | async e await, sem travar a execução |
| Testes estruturados | As três fases do teste ficam visíveis, e a asserção não carrega expressão |
Ver todas as linguagens
| Linguagem | Descrição |
|---|---|
| HTML | Semântica, acessibilidade, performance, SEO e jQuery |
| JavaScript | Fundamentos ilustrados com JS: variáveis, funções, fluxo, async |
| TypeScript | Tipos, interfaces, narrowing, generics, null-safety |
| CSS | BEM, variáveis do CSS, tela pequena primeiro, Tailwind, Bootstrap, shadcn/ui e Lucide |
| C# | Convenções C#/.NET: records, Result<T>, async, LINQ |
| VB.NET | Convenções VB.NET/.NET Framework 4.8: legado, async, LINQ |
| Python | Convenções Python 3.14: dataclasses, async, Pydantic, match/case |
| Go | Convenções Go 1.26: structs, interfaces, goroutines, error values |
| PHP | Convenções PHP 8.4: readonly, enums, traits, Fibers, PSR-12 |
| Kotlin | Convenções Kotlin 2.2: coroutines, sealed classes, K2 compiler |
| Swift | Convenções Swift 6.1: actors, async/await, Sendable, strict concurrency |
| Dart | Convenções Dart 3.7: null safety, records, streams, sealed classes |
| Flutter | Framework Flutter 3.29: widgets, GoRouter, Riverpod, platform channels |
| Java | Convenções Java 25 LTS: records, sealed classes, virtual threads, Spring Boot |
| SQL | Formatação e nomenclatura para SQL Server, PostgreSQL e SQLite |
| NoSQL | MongoDB, Redis, DynamoDB, Cassandra e Elasticsearch |
Ver todos os conceitos
Processo: como o time trabalha e entrega
| Tópico | Descrição |
|---|---|
| Governance | Pensamento de staff engineer, SDLC, onboarding e governança do projeto |
| Methodologies | DDD, BDD, TDD, XP, XGH, desenvolvimento orgânico + Monolito, Microsserviços, Monolito Modular |
| Agile | Manifesto, Scrum, Kanban, Lean, cascata, histórias de usuário e definição de pronto |
| BPM | BPMN, raias e desvios, orquestração e coreografia, motor de processo e máquina de estados |
| Git | Branches, commits, pull requests e estratégia de entrega |
| Git (avançado) | Rotina de uma tarefa, squash, review e recuperação de erros |
| Design Thinking | Empatia, definição de problema, ideação, protótipo e teste centrado no usuário |
| Design Thinking (avançado) | Double Diamond, Service Blueprint, Crazy 8s, SCAMPER, MVP e MLP e usability testing |
| CI/CD | Pipeline, deploy e release, feature flags, TBD e fix forward |
Arquitetura: como o código é estruturado
| Tópico | Descrição |
|---|---|
| Principles | Todos os princípios explicados: Forma, Legibilidade, Controle de Qualidade |
| SOLID | Uma seção por letra: SRP, OCP, LSP, ISP e DIP, com sinal de violação e custo do excesso |
| Principles (avançado) | KISS, YAGNI, DRY e a regra das três, separação de responsabilidades, Deméter, menor surpresa |
| System Design | Requisitos funcionais e não-funcionais, decomposição, trade-offs essenciais |
| System Design (avançado) | SLA/SLO/SLI, CAP, PACELC, modelos de consistência, sharding, replicação e capacity planning |
| Architecture | Vertical Slice, MVC, Legacy, XP e XGH com estrutura de pastas |
| Component Architecture | Composição, container/presentational, estado, memoization, limites de módulo |
| Patterns | Os 23 padrões GoF em criacionais, estruturais e comportamentais, com exemplo ruim e bom |
| Patterns (avançado) | Result, Repository, Specification, Null Object, Unit of Work, CQRS, Circuit Breaker, DI, SDD |
| Entity Modeling | Tamanho saudável, value objects, strongly-typed IDs, BaseEntity, cardinalidade, 1:N e N:N |
| Transactions | Boundary transacional, Unit of Work, locking otimista/pessimista, saga, eventual consistency |
| Domain Events | Domain vs integration event, outbox, naming no passado, schema versionado, handler isolation |
| Scaling | Load Balancing, API Gateway, escala vertical e horizontal, estratégias e anti-overengineering |
| Operation Flow | Fluxo de operação backend e frontend: puro nas bordas, I/O no meio, CQS |
| Frontend Flow | Routing, guards, loaders, layouts aninhados, forms e updates otimistas |
| Backend Flow | Background jobs, webhooks e event-driven: outbox, idempotência, DLQ e envelope |
Qualidade: como o código é escrito
| Tópico | Descrição |
|---|---|
| Control Flow | Quando usar cada ferramenta de fluxo: tabela semântica simples → complexo |
| Visual Density | Densidade visual agnóstica de linguagem: princípios e regras |
| Null Safety | Limite vs interior, contratos de entrada e schema evolution |
| Testing | AAA, no logic no assert, testes unitários e de integração |
| Observability | Logging estruturado, níveis, PII, correlation ID |
| UI/UX | Espaçamento, tipografia, temas claro/escuro, acessibilidade e estados |
| Color Theory | OKLCH, círculo cromático, harmonias, composição 60-30-10, WCAG, hierarquia de superfícies, escala tonal 50-950 |
| EditorConfig | Configuração base de editor compatível com qualquer stack |
Plataforma: infraestrutura e configuração
| Tópico | Descrição |
|---|---|
| Desenho de API | Pipeline BFF, contratos Request/Response, envelope padrão, verbos REST, status codes e Result → HTTP |
| Segurança | Segredos, configuração em camadas, autorização e flags do cookie de sessão |
| Segurança avançada | OWASP Top 10:2025, hash de senha, CSP e headers, cadeia de suprimentos, ASVS e pós-quântico |
| Autenticação | OAuth e OIDC, JWT e JOSE, cookie por dentro, cache e ETag, token no navegador e no app mobile, passkeys |
| Configuração | Config e secret, precedência, camadas por ambiente, objeto tipado e fail-fast |
| Feature flags | Toggle por propósito, rollout, dark launch, kill switch e prazo de validade |
| Desempenho | Paginação, cache, filas assíncronas, webhook, polling, WebSocket, lazy loading e Big O |
| Banco de dados | SQL vs NoSQL, tuning de queries, operações em lote, plano de execução e troubleshooting |
| NoSQL | MongoDB, Redis, DynamoDB, Cassandra e Elasticsearch: convenções, SGBD e scripts |
| ETL e BI | OLTP vs OLAP, pipeline de dados, extração incremental, ELT, modelagem dimensional, SCD e BI |
| Formatos e integrações | GraphQL, TOML, YAML, XML/SOAP (NF-e, CT-e), CNAB, SPED, ZPL e porta serial |
| Mensageria | Broker, queue, pub/sub, garantias de entrega, DLQ, idempotência e backpressure |
| Bots de mensageria | Webhook e polling, roteamento de comando, sessão, teto de envio e ciclo de vida |
| Computação em nuvem | Serviços gerenciados, permissão mínima, containers e ambientes |
| Dispositivos IoT | Debounce, máquina de estados, alerta idempotente, watchdog e polling vs IRQ |
IA (Inteligência Artificial): modelos, agentes e integração com LLMs
| Tópico | Descrição |
|---|---|
| Modelos | Escolher entre nuvem e máquina local: Claude, GPT, Gemini, Llama, Mistral, Ollama e quantização |
| Agentes | O loop do agente, o harness que o executa, orquestração, multi-agente e memória |
| RAG | Responder com base em documentos recuperados: embeddings, vector store e chunking |
| Tool use e MCP | Dar ao modelo acesso ao mundo externo: tool use, function calling e o protocolo MCP |
| Tokens | A unidade que o modelo lê e a que a conta mede: janela de contexto, custo e cache de prompt |
| Engenharia de prompts | Escrever a instrução que o modelo entende, com exemplos BAD/GOOD |
| Skills | Empacotar um comportamento do agente: roteamento, carregamento sob demanda e composição |
| Conceitos avançados | Ajuste fino, alucinação, saídas estruturadas, raciocínio estendido, motores de inferência e AI Gateway |
Mobile: fundamentos cross-platform para Android, iOS e Flutter
| Tópico | Descrição |
|---|---|
| Ciclo de vida do aplicativo | Estados do app, cold e warm start, process death e impacto na experiência |
| Navegação entre telas | Pilha, barra de abas, modal, deep link e back stack |
| Gerenciamento de estado | Estado da tela e estado do domínio, fluxo unidirecional e reatividade |
| Offline-first | Estratégias de cache, sincronização, resolução de conflito e estado da rede |
| Permissões do dispositivo | Permissões em tempo de execução, negação definitiva e fluxo de solicitação |
Ver CHANGELOG.md para o histórico de versões e releases.
Ver REFERENCES.md para todos os links organizados por tema.
Correções e propostas são bem-vindas. O caminho, os gates de qualidade (npm run audit:docs) e o estilo dos exemplos estão em CONTRIBUTING.md.
Conteúdo publicado sob CC BY 4.0: use, adapte e redistribua com atribuição.