README.md

JavaScript

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