NetFabric/NetFabric.Numerics / .agents/skills/csharp-best-practices
csharp-best-practices
VerifiedModern .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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.7 KB |
| references/async.md | markdown | 3.8 KB |
| references/language-features.md | markdown | 3.9 KB |
| references/performance.md | markdown | 4.2 KB |
| references/source-generators.md | markdown | 3.5 KB |
references/language-features.md
View on GitHub# Language Features
## Records & Structs
```csharp
// readonly record struct — best for small immutable value types
public readonly record struct Point(double X, double Y);
// record class — immutable reference type with value equality
public record class Person(string Name, int Age);
// with-expression works on both
var p2 = p1 with { X = 3.0 };
```
**Struct guidelines:**
- Add `readonly` to prevent defensive copies when passed as `in`
- Keep ≤4 fields; larger structs are slower to copy than references
- Implement `IEquatable<T>` explicitly for `struct` (auto-generated for records)
## Primary Constructors (C# 12)
```csharp
// Parameters are captured as fields implicitly — do NOT re-declare them
public class Service(ILogger<Service> logger, IRepository repo)
{
public async Task DoWork() => await repo.SaveAsync();
// logger and repo are in scope everywhere in the class
}
// readonly record struct with primary ctor — canonical pattern
public readonly record struct Angle<TUnits, T>(T Value)
where TUnits : IAngleUnits<TUnits>
where T : struct, INumber<T>;
```
## Required Members (C# 11)
```csharp
public class Config
{
public required string ConnectionString { get; init; }
public required int MaxRetries { get; init; }
public int TimeoutMs { get; init; } = 5000; // optional, has default
}
// Enforced at call site:
var cfg = new Config { ConnectionString = "...", MaxRetries = 3 };
```
## Collection Expressions (C# 12)
```csharp
// Prefer over new List<>(), new int[], Array.Empty<>(), Enumerable.Empty<>()
int[] nums = [1, 2, 3];
List<string> names = ["Alice", "Bob"];
ReadOnlySpan<byte> empty = [];
// Spread operator
int[] combined = [..a, ..b];
```
## Pattern Matching
```csharp
// Switch expression — prefer over switch statement for mapping
string Describe(Shape s) => s switch
{
Circle { Radius: > 10 } c => $"large circle r={c.Radius}",
Circle c => $"small circle r={c.Radius}",
Rectangle { Width: var w, Height: var h } when w == h => "square",
Rectangle r => $"rect {r.Width}x{r.Height}",
_ => "unknown"
};
// is-pattern with property pattern
if (result is { IsSuccess: true, Value: var value })
Process(value);
// List patterns (C# 11)
if (args is [var first, ..])
Console.WriteLine(first);
```
## Raw String Literals (C# 11)
```csharp
// No escaping needed; leading indent stripped
var json = """
{
"name": "Alice",
"path": "C:\\Users\\Alice"
}
""";
// Interpolated raw strings
var query = $"""
SELECT *
FROM {tableName}
WHERE id = {id}
""";
```
## Nullable Reference Types
```csharp
// Project-wide in .csproj:
// <Nullable>enable</Nullable>
// Return null only for "not found"; never for empty collections
public string? FindById(int id) => _dict.GetValueOrDefault(id);
public IReadOnlyList<Item> GetAll() => _items; // never null
// Null-coalescing assignment
_cache ??= new Dictionary<string, object>();
// Null-conditional with index
var first = list?.Count > 0 ? list[0] : null;
```
## Using Declarations & Disposal
```csharp
// Prefer using declaration (C# 8) over using block when scope is clear
using var stream = File.OpenRead(path);
using var reader = new StreamReader(stream);
// disposed at end of enclosing scope
// IAsyncDisposable
await using var conn = await OpenConnectionAsync();
```
## Miscellaneous
| Anti-pattern | Replacement |
|-------------|-------------|
| `if (x == null)` | `if (x is null)` (reference semantics) |
| `if (x != null)` | `if (x is not null)` |
| `(Foo)bar` cast | `bar as Foo` + null check, or `is Foo f` pattern |
| Hardcoded param name in exception | `throw new ArgumentNullException(nameof(x))` |
| Magic numbers | `const` or `static readonly` |
| `string.Format(...)` | string interpolation `$"..."` |
| `+=` on string in loop | `StringBuilder` or `string.Create()` |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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 implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |