|
| 1 | +--- |
| 2 | +applyTo: "**/*.cs" |
| 3 | +--- |
| 4 | + |
| 5 | +# C#/.NET Guidelines |
| 6 | + |
| 7 | +## Coding style |
| 8 | + |
| 9 | +For all new C# code: |
| 10 | + |
| 11 | +- Use file-scoped namespaces. |
| 12 | +- Use collection expresions - write `[1, 2, 3]` and not `new List<int> { 1, 2, 3 }`. |
| 13 | +- Use `var` for local variable declarations. |
| 14 | +- Use switch expressions and pattern matching. |
| 15 | +- Use string interpolation (`$"Hello, {name}!"`) instead of `string.Format` or concatenation. |
| 16 | +- Use `"""triple-quoted strings"""` for multi-line string literals. These can be interpolated as well. |
| 17 | +- Use expression-bodied members for simple getters and setters. |
| 18 | + |
| 19 | +## Code Design Rules |
| 20 | + |
| 21 | +- Use immutable records instead of classes for DTOs. |
| 22 | +- Do not default to `public` accessibility for members and classes. Follow the least-exposure rule: `private` > `internal` > `protected` > `public` |
| 23 | +- Do not add unused methods/parameters for use cases that were not asked for. |
| 24 | +- Reuse existing methods or services as much as possible. |
| 25 | +- Use composition over inheritance. |
| 26 | + |
| 27 | +## Error Handling & Edge Cases |
| 28 | + |
| 29 | +- Guard early; use `string.IsNullOrWhiteSpace`, `ArgumentNullException.ThrowIfNull`, or `ArgumentNullException.ThrowIfNullOrWhiteSpace`. |
| 30 | +- Avoid using null for control flow. |
| 31 | +- In methods that return collections, return empty collections instead of null. |
| 32 | +- The null-forgiving operator (`!`) is **always** a code smell. |
| 33 | +- Do not add excessive or unnecessary try/catch blocks within the same assembly. |
| 34 | + |
| 35 | +## Async Best Practices |
| 36 | + |
| 37 | +- All async methods must have names ending with `Async`. |
| 38 | +- Always await async methods - do not "fire and forget". |
| 39 | +- Always accept and pass along a `CancellationToken` in async code. |
| 40 | +- Don’t add `async/await` if you can simply return a Task directly. |
| 41 | + |
| 42 | +## Testing |
| 43 | + |
| 44 | +- Use Shouldly when writing new assertions. |
| 45 | +- Use clear assertions that verify the outcome expressed by the test name. |
| 46 | +- Tests should be able to run in any order or in parallel. |
| 47 | +- Use or add helper methods for constructing mocks and complex test data objects. |
| 48 | +- Avoid disk I/O if possible; use in-memory alternatives or mocks. |
| 49 | +- Do not add "Arrange-Act-Assert" comments. |
| 50 | + |
| 51 | +## Comments |
| 52 | + |
| 53 | +- Add XML documentation comments for for new **public** or **internal** types and members. |
| 54 | +- Comments that simply restate the member or parameter name do not provide value. |
| 55 | +- Comments should provide additional context or explain non-obvious behavior, especially for parameters. |
| 56 | +- Comments inside methods should explain "why," not "what". |
| 57 | +- Avoid redundant comments that restate the code - not all code needs comments. |
0 commit comments