Readme
JavaScript é a linguagem usada para ilustrar os fundamentos deste guia. A maioria dos princípios aqui (nomes expressivos, guard clauses, funções pequenas, fluxo linear) são transportáveis para qualquer linguagem.
→ Quick Reference: nomenclatura, verbos, taboos, tipos, controle de fluxo
Setup
Configuração inicial de um projeto Node.js: estrutura, módulos e pipeline.
| Tópico | Conceitos |
|---|---|
| Security | Secrets, env vars, dotenv, cadeia de config |
| Project Foundation | Entry point, módulos, config, pipeline |
Fundamentos
| Tópico | Conceitos |
|---|---|
| Variables | const, let, valor fixo por padrão |
| Naming | camelCase, UPPER_CASE, ordem semântica, inglês |
| Functions | Tamanho, top-down, direct return |
| Control Flow | Guard clauses, early return, iterações |
| Visual Density | Agrupamento de linhas, return separado, fases de método |
Avançados
| Tópico | Conceitos |
|---|---|
| Error Handling | Erros tipados, try/catch nos limites do sistema |
| Async | async/await, evitar bloqueio |
| Testing | AAA, semantic assert, isolamento |
| Performance | for...of, Set, string building |
| Observability | Logging estruturado, níveis, PII, correlationId |
| Validation | Sanitize, Zod, regras de negócio, output filter |
| Dates | UTC, ISO 8601, parsing, Temporal API |
| Entity Modeling | Lean pointer ao canônico shared, #field privacy, Object.freeze, Symbol.iterator, instanceof boundary |
| Quick Reference | Nomenclatura, verbos, taboos |
Frameworks
| Tópico | Conceitos |
|---|---|
| Bot Discord | discord.js: Client, Gateway Intents, Slash Commands, Embeds |
| Bot Telegram | Telegraf: commands, Inline Keyboard, middleware, webhook |
| Bot WhatsApp | Baileys e Meta Cloud API: webhook, Template Messages, command router |
| Bot Slack | Bolt for JS: slash commands, Events API, Block Kit, Socket Mode |
Princípios
Forma: estrutura e narrativa da função
| Princípio | Descrição |
|---|---|
| Escrita em inglês | Código universal, nomes curtos e sem ambiguidade |
| Código narrativo | O código conta a história, sem precisar de comentários |
| Ponto de entrada limpo | Caller de uma linha: o quê, não o como |
| Estilo vertical | Até 3 parâmetros por linha; 4+ usa objeto |
| Orquestrador no topo | Chamada visível antes dos detalhes (top-down) |
| Detalhes abaixo | Helpers ficam abaixo do orquestrador (step-down rule) |
| Sem lógica no retorno | Saída de uma linha: o retorno nomeia o resultado, não o computa |
Legibilidade: fluxo, densidade visual e nomes
| Princípio | Descrição |
|---|---|
| Retorno antecipado | Saída cedo na falha, sem else após return |
| Fluxo linear | Aninhamento em cascata substituído por fluxo plano |
| Baixa densidade visual | Linhas relacionadas juntas, grupos separados por uma linha em branco |
| Nomes expressivos | Variáveis e funções que dispensam explicação |
| Código como documentação | Nomes substituem comentários; comentários mentem |
| Sem valores mágicos | Constantes nomeadas no lugar de números e strings soltos |
Controle de qualidade: estado, erros, async e testes
| Princípio | Descrição |
|---|---|
| Funções pequenas | Uma responsabilidade, um nível de abstração |
| Cálculo vs formatação | Computar dados e formatar saída em funções separadas |
| Valor fixo por padrão | const primeiro, let só quando necessário |
| CQS | Separar comando de consulta, sem efeitos colaterais ocultos |
| Dependências explícitas | Injetar via parâmetros, evitar estado global |
| Falhar rápido | Validar cedo, interromper fluxo inválido |
| Retorno explícito | Evitar exceções como controle de fluxo |
| Contratos consistentes | Respostas padronizadas, sempre o mesmo formato |
| Tratamento centralizado de erros | Classes de erro tipadas, try/catch nos limites do sistema |
| I/O assíncrono | async/await, sem bloqueio |
| Testes estruturados | AAA: fases explícitas; assert limpo: sem expressões inline |
Desenvolvido por @thiagocajadev · Fork baseado no repositório pmndrs/docs · Poimandres.