Readme
JavaScript é a linguagem que este guia usa para mostrar os fundamentos, porque ela deixa cada decisão à vista: nada obriga a nomear bem, a sair cedo de uma função ou a manter o fluxo plano. O que você aprende aqui viaja com você. Nomes expressivos, guard clauses, funções pequenas e fluxo linear valem igual em C#, Python ou Go, e cada página aponta o equivalente na outra linguagem quando ele existe.
→ Referência rápida: nomenclatura, verbos, nomes proibidos, tipos, controle de fluxo
Setup
O que se decide antes da primeira linha de domínio: onde a configuração é lida, como os módulos se dividem e onde os segredos ficam.
| Tópico | Conceitos |
|---|---|
| Fundação do projeto | Entry point, módulos por domínio, config, middleware |
| Segurança | Segredos, variáveis de ambiente, dotenv, JWT |
Fundamentos
| Tópico | Conceitos |
|---|---|
| Variáveis | const, let, valor fixo por padrão |
| Nomes | camelCase, UPPER_CASE, ordem semântica, inglês |
| Funções | Tamanho, top-down, retorno direto |
| Controle de fluxo | Guard clauses, retorno antecipado, iterações |
| Densidade visual | Agrupamento de linhas, return separado, fases do método |
Avançados
| Tópico | Conceitos |
|---|---|
| Tratamento de erros | Erros tipados, try/catch nos limites do sistema |
| Programação assíncrona | async/await, evitar bloqueio |
| Testes | AAA, assert com significado, isolamento |
| Performance | for...of, Set, montagem de string |
| Observabilidade | Log estruturado, níveis, PII, correlationId |
| Validação | Sanitize, Zod, regras de negócio, filtro de saída |
| Datas | UTC, ISO 8601, interpretação de texto, Temporal API |
| Modelagem de entidades | Ponteiro enxuto ao canônico shared, privacidade com #field, Object.freeze, Symbol.iterator, instanceof no limite |
| Referência rápida | Nomenclatura, verbos, nomes proibidos |
Frameworks
| Tópico | Conceitos |
|---|---|
| Bot Discord | discord.js: conexão ao Gateway, intents, slash commands, embeds |
| Bot Telegram | Telegraf: comandos, botões inline, middleware, webhook |
| Bot WhatsApp | Baileys e Meta Cloud API: sessão, webhook, mensagem por template |
| Bot Slack | Bolt for JS: ack em 3s, eventos, 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 |
DoDocs v3.7.0 · Desenvolvido por @thiagocajadev · Baseado no trabalho de pmndrs/docs · Poimandres.