Readme
As convenções do guia aplicadas ao C# e ao .NET. A linguagem oferece um recurso para quase toda
decisão de design, e a maior parte destas páginas trata de escolher entre eles: quando record e
quando class, quando Result e quando exceção, quando var e quando o tipo escrito por extenso.
Os exemplos usam C# 14 e .NET 10, e o texto avisa quando uma versão anterior se comporta de outro
jeito.
→ Referência rápida: nomenclatura, modificadores, tipos, LINQ, controle de fluxo
Setup
Configuração inicial de um projeto C#/.NET: estrutura, infraestrutura e segurança.
| Tópico | Conceitos |
|---|---|
| Fundação do projeto | Program.cs enxuto, extension methods, rate limiting, pipeline |
| Segurança | Secrets, env vars, user-secrets, cadeia de configuração |
| Fatia vertical | IModule, descoberta automática, AddDefaults/UseDefaults, os seis passos, CQS |
| Entity Framework | AsNoTracking, projeção, N+1, paginação, OrderBy, left join |
| Dapper | Procedures por domínio, queries simples, injeção de conexão |
Fundamentos
| Tópico | Conceitos |
|---|---|
| Variáveis | var, const, readonly, record para dados fixos |
| Nomes | PascalCase, _camelCase, prefixo I, sufixo Async |
| Métodos | Um nível de abstração, orquestrador, construtor primário |
| Controle de fluxo | Guard clauses, pattern matching, switch expressions |
| Densidade visual | Fases do método, o respiro antes do return, declaração + guarda |
Avançados
| Tópico | Conceitos |
|---|---|
| Tratamento de erros | Result<T>, ApiError, exceção só para o inesperado |
| Assincronia | async/await, Task.WhenAll, CancellationToken |
| LINQ | Coleções, Select e foreach, materialização, left join |
| Injeção de dependências | Injeção por construtor, tempo de vida, interface para teste |
| Design de API | Minimal API, fatia vertical, controllers, DTOs, status codes |
| Testes | AAA, assert com valores nomeados, isolamento |
| Desempenho | Span<T>, StringBuilder, ValueTask |
| Observabilidade | Logging estruturado, níveis, PII, id de correlação |
| Validação | Limpeza, FluentValidation, regras de negócio, filtro de saída |
| Datas | DateTimeOffset, DateOnly, UTC, ida e volta ao banco |
| Modelagem de entidades | record struct para IDs, IReadOnlyList, Entity<TId>, factory + private setters |
| Referência rápida | Nomenclatura, verbos, nomes proibidos, convenções rápidas |
Frameworks
| Tópico | Conceitos |
|---|---|
| Blazor | Render modes, componentes, estado, formulários, roteamento, JS Interop |
| Razor Pages e MVC | PageModel, Tag Helpers, controller thin, ViewModel, layouts, partial views |
Princípios
Forma: estrutura e narrativa do método
| Princípio | Descrição |
|---|---|
| Escrita em inglês | Código universal, nomes curtos e sem ambiguidade |
| PascalCase e _camelCase | Público PascalCase, privado _camelCase |
| Sufixo Async | Todo método assíncrono termina em Async |
| Nomes expressivos | Variáveis e métodos que dispensam explicação |
| Código como documentação | Nomes substituem comentários: comentários mentem |
| Orquestrador no topo | Chamada visível antes dos detalhes: top-down |
| SLA | Uma responsabilidade, um nível de abstração |
| 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 |
| Pattern matching | switch expressions sobre if-else encadeado |
| Valor fixo por padrão | readonly, const, record: alteração é exceção explícita |
| Sem valores mágicos | Constantes nomeadas em vez de literais inline |
| CQS | Retornar novo estado, sem efeitos colaterais ocultos |
Controle de qualidade: estado, erros, async e testes
| Princípio | Descrição |
|---|---|
| Primary constructors | DI por construtor primário, sem service locator |
| Result<T> | Exceção para falhas inesperadas; Result para fluxo de negócio |
| Falhar rápido | Validar cedo, interromper fluxo inválido |
| Contratos consistentes | Erros tipados, sempre o mesmo formato |
| I/O assíncrono | async/await: nunca .Result ou .Wait() |
| CancellationToken | Propagado em todas as chamadas de I/O públicas |
| Concorrência explícita | Task.WhenAll para chamadas independentes em paralelo |
| LINQ puro | Query transforma dados; efeitos colaterais ficam no foreach |
| 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.