Skip to content

NetFabric/NetFabric.Numerics / .agents/skills/csharp-best-practices

csharp-best-practices

Verified

Modern .NET and C# best practices for code quality, performance, and correctness. USE FOR: choosing struct/class/record/readonly-record-struct; nullable reference types; pattern matching; primary constructors; collection expressions; required members; init-only properties; file-scoped namespaces; global usings; async/await patterns; ConfigureAwait; ValueTask vs Task; CancellationToken propagation; IAsyncEnumerable; Span<T>/Memory<T> usage; avoiding boxing; readonly struct; ArrayPool<T>; FrozenDictionary/FrozenSet; LINQ vs loops in hot paths; ArgumentNullException.ThrowIfNull; ThrowIfNegative; ThrowIfZero; IReadOnlyList return types; error handling patterns; GeneratedRegex; LoggerMessage; source generators for regex and logging; avoiding Math/MathF in favor of static methods on the numeric type. DO NOT USE FOR: generic math interfaces (use dotnet-generic-math); ASP.NET Core middleware; EF Core modeling.

FileKindSize
SKILL.mdskill md4.7 KB
references/async.mdmarkdown3.8 KB
references/language-features.mdmarkdown3.9 KB
references/performance.mdmarkdown4.2 KB
references/source-generators.mdmarkdown3.5 KB

references/async.md

View on GitHub
# Async / Await

## Core Rules

| Rule | Rationale |
|------|-----------|
| Never `async void` (except event handlers) | Exceptions are unobservable; prefer `async Task` |
| Never `.Result` / `.Wait()` on a `Task` | Deadlocks in sync contexts (ASP.NET, UI) |
| Pass `CancellationToken` as last param | Propagate from caller to every I/O call |
| Await every `Task` returned | Suppress only with explicit `_ = FireAndForget()` and a reason |
| Don't `await` in a `finally` block | Use `IAsyncDisposable` instead |

## ConfigureAwait

```csharp
// Library code — always use ConfigureAwait(false) to avoid deadlocks
public async Task<Data> LoadAsync(CancellationToken ct = default)
{
    var raw = await _client.GetAsync(url, ct).ConfigureAwait(false);
    return await ParseAsync(raw, ct).ConfigureAwait(false);
}

// Application code (ASP.NET Core, console) — omit ConfigureAwait(false)
// ASP.NET Core has no SynchronizationContext so it doesn't matter, but
// omitting is conventional in app code.
```

## ValueTask vs Task

| Scenario | Use |
|----------|-----|
| Result is usually available synchronously (cache hit, memory) | `ValueTask<T>` |
| Always async (network, disk I/O) | `Task<T>` |
| Fire-and-forget | `Task` (never `void`) |
| Hot path, allocation-sensitive, sync fast-path | `ValueTask` |

```csharp
// ValueTask — avoid awaiting more than once or storing for later
public ValueTask<int> ReadCachedAsync(string key, CancellationToken ct = default)
{
    if (_cache.TryGetValue(key, out var val))
        return ValueTask.FromResult(val);   // no allocation on cache hit

    return new ValueTask<int>(FetchFromDbAsync(key, ct));
}
```

Never call `.Result` on a `ValueTask`; never await a `ValueTask` more than once.

## CancellationToken

```csharp
// Accept as last param with default
public async Task ProcessAsync(string input, CancellationToken ct = default)
{
    ct.ThrowIfCancellationRequested();              // fast check before work
    var result = await _service.CallAsync(input, ct).ConfigureAwait(false);
    await _store.SaveAsync(result, ct).ConfigureAwait(false);
}

// Link timeouts with cancellation
using var cts = CancellationTokenSource.CreateLinkedTokenSource(externalCt);
cts.CancelAfter(TimeSpan.FromSeconds(30));
await ProcessAsync(data, cts.Token);
```

## IAsyncEnumerable\<T\>

```csharp
// Producer — yield inside async method
public async IAsyncEnumerable<Record> StreamAsync(
    [EnumeratorCancellation] CancellationToken ct = default)
{
    await foreach (var batch in _db.ReadBatchesAsync(ct))
        foreach (var item in batch)
            yield return item;
}

// Consumer
await foreach (var record in source.StreamAsync(ct))
    await ProcessAsync(record, ct);
```

`[EnumeratorCancellation]` lets callers pass a token via `.WithCancellation(ct)` on the consumer side.

## Parallelism

```csharp
// Concurrent independent tasks — collect then await all
var taskA = _svc.GetA(ct);
var taskB = _svc.GetB(ct);
await Task.WhenAll(taskA, taskB);
var (a, b) = (taskA.Result, taskB.Result);   // safe after WhenAll

// Bounded parallel with Parallel.ForEachAsync (.NET 6+)
await Parallel.ForEachAsync(items, new ParallelOptions
{
    MaxDegreeOfParallelism = Environment.ProcessorCount,
    CancellationToken = ct
}, async (item, innerCt) =>
{
    await ProcessAsync(item, innerCt).ConfigureAwait(false);
});
```

## Common Anti-patterns

| Anti-pattern | Fix |
|-------------|-----|
| `async Task Foo() { return await Bar(); }` | `Task Foo() => Bar();` (drop async/await) |
| `Task.Run(() => Foo())` to go async | Expose truly async API; don't wrap sync code |
| `Task.Delay(0)` to yield | `await Task.Yield()` (explicit) |
| `new Task(...)` + `.Start()` | `Task.Run(...)` |
| Catching `TaskCanceledException` to swallow | Re-throw or handle intentionally |
| `async` lambda in `List.ForEach` | `foreach` loop with `await` |
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall