Style & Quality
Consistency keeps Kestrun approachable. Follow these guidelines for C# and PowerShell.
C# Guidelines
| Area | Rule |
|---|---|
| Public APIs | Explicit types, nullable enabled |
| Async | Use ConfigureAwait(false) in library code |
| Naming | PascalCase for public members, _camelCase for private fields |
| Exceptions | Throw specific types; avoid swallowing errors silently |
| Logging | Use provided logging abstractions / Serilog integration |
Prefer small, composable classes. Avoid static mutable state.
PowerShell Guidelines
| Area | Rule |
|---|---|
| Cmdlet Verbs | Use approved verbs (Get, Set, New, Remove, Test, Invoke) |
| Function Help | Comment-based help required for public functions |
| Pipeline | Support pipeline input where natural |
| Parameters | Use parameter attributes for validation (ValidateSet, etc.) |
| Error Handling | Throw for unrecoverable issues; otherwise Write-Error |
Prefer idempotent operations and fast fail semantics.
Testing Principles
| Topic | Guidance |
|---|---|
| Granularity | One assertion concept per test |
| Determinism | No external network/timezone surprises |
| Coverage | Focus on critical logic paths first |
| Naming | Method_Scenario_Expectation |
| Isolation | Avoid shared mutable global state |
Logging Style
Follow the emoji/status conventions in the Logging & Console Output guide.
Documentation Quality
- Keep introductions concise.
- Use active voice.
- Provide runnable code where possible.
- Cross-link related pages.
Pull Request Expectations
| Requirement | Reason |
|---|---|
| Tests updated/added | Guard against regressions |
| Docs aligned | User discoverability |
| Build passes | Baseline confidence |
| Style followed | Consistency |
| No dead code | Reduce maintenance burden |
Anti-Patterns (Avoid)
| Anti-Pattern | Why to Avoid |
|---|---|
| Large God classes | Hard to test and extend |
| Hidden side effects | Surprising consumer behavior |
Catch-all try { } catch { } | Masks real failures |
| Premature optimization | Obscures readability |
| Overusing dynamic | Hurts analyzability + perf |
Last updated: 2025-09-03