Skip to content

dotnet-awesome-humans

Opinionated best practices for modern .NET.

Distils the published guidance of awesome humans: people and publications with a proven, multi-year track record, catalogued in AWESOME-HUMANS.md. Aims to answer the question "what does good look like in .NET right now?" and to keep answering it as .NET improves.

How to use this project:

  • Point an agent at it. "Follow the conventions in https://github.com/si618/dotnet-awesome-humans when writing .NET code." The opinions cover conventions, project layout, language usage, and library choices.
  • Scaffold from it. Copy files out of templates/, or run verify-project against a codebase you already have.
  • Read it. At awesome-humans.net, or here on GitHub. Every opinion starts with the recommendation, then the rationale, then the sources, with code examples where it makes sense.

Scope

The main areas of modern .NET. The opinions live in opinions/, one topic per file:

  • Application architecture: modular monolith, vertical slices, and when layering is worth its cost
  • ASP.NET Core: minimal APIs, hosting, auth, OpenAPI, performance
  • C#: the latest released language version, and idiomatic use of what it added
  • CI & automation: pinned, reproducible builds and supply-chain hygiene
  • Data access: EF Core defaults, set-based work, when to drop to SQL
  • Dates, times & time zones: type choice, UTC vs local storage, TimeProvider, testing time
  • F#: domain modelling, mixed C#/F# solutions, testing
  • Globalization & localization: culture vs ordinal, ICU and invariant mode, IStringLocalizer, and the data containers drop
  • Logging & tracing: structured logging, source-generated log messages, OpenTelemetry over OTLP
  • Project structure & SDK: project files, solution formats, central package management, analyzers, source generators
  • Runtime & BCL: performance idioms, Span<T>/memory, async, GC awareness
  • Testing: framework choice, naming and structure, integration tests, coverage
  • UI frameworks: Blazor/WebAssembly, .NET MAUI, and cross-platform desktop (Avalonia)
  • Libraries: what to use and what to avoid, spread across the files above

Freshness policy

Opinions target the latest released versions of .NET, C#, and F#, never an older LTS, with preview features confined to "Coming next" asides. New versions are folded in by the skills below.

Every resource records when it was last reviewed, so staleness is visible, and opinions/ and templates/ also record when each was last used as a reference. Opinions and research topics carry the fields as YAML frontmatter; templates carry them in a first-line comment header, because an XML or INI file cannot open with a --- block. AGENTS.md: Metadata defines the fields and their rules, and CI enforces them.

Awesome humans

Opinions have to be earned. Each one traces back to a vetted source: an individual (Stephen Toub, Andrew Lock) or a publication (the .NET Blog, Microsoft Learn). Admission is on track record: two years of sustained writing at minimum, plus depth, accuracy, and independence of signal. Video, talks and podcasts are out of scope at this stage, because an opinion cites text a reader can check. The roster and the full criteria are in AWESOME-HUMANS.md.

How a source gets in, and what its standing lets it do (orientation only: the admission criteria in AWESOME-HUMANS.md and the vet-source skill are canonical):

Source standing: vet-source sorts a candidate into citable, watch list or declined, and a citable source is unmarked, Corroborate or Discovery-only

Standing is never permanent. vet-source runs again when an admitted source goes dormant or drops in quality, and when a watch-listed source's blocker clears. There is one citable tier, and two markings in a source's notes section narrow what a citation may rest on: a **Corroborate.** source is never the only citation on a claim, and a **Discovery-only.** source is never cited at all, only followed to the primary source it points at. Anything else that limits a source, such as an independence concern or a back catalogue that has aged out, is written into its notes as prose rather than encoded in its standing.

House opinions

One human outranks the roster: the repository owner. Their preferences enter through HOUSE-OPINIONS.md and the weave-house-opinion skill, and are always marked in place, so a reader can tell community best practice from local convention. HOUSE-OPINIONS.md defines the marking literal and what wins when the two conflict. Other contributors propose opinions, sourced or experience-based, through the pull request template.