|
| 1 | +## General |
| 2 | + |
| 3 | +- Make only high confidence suggestions when reviewing code changes. |
| 4 | +- Always use the latest version C#, currently C# 13 features. |
| 5 | +- Write code that is clean, maintainable, and easy to understand. |
| 6 | +- Only add comments rarely to explain why a non-intuitive solution was used. The code should be self-explanatory otherwise. |
| 7 | +- Don't add the UTF-8 BOM to files unless they have non-ASCII characters. |
| 8 | +- Never change global.json unless explicitly asked to. |
| 9 | +- Never change package.json or package-lock.json files unless explicitly asked to. |
| 10 | +- Never change NuGet.config files unless explicitly asked to. |
| 11 | + |
| 12 | +## Code Style |
| 13 | + |
| 14 | +### Formatting |
| 15 | + |
| 16 | +- Apply code-formatting style defined in `.editorconfig`. |
| 17 | +- Use primary constructors where applicable. |
| 18 | +- Prefer file-scoped namespace declarations and single-line using directives. |
| 19 | +- Insert a newline before the opening curly brace of any code block (e.g., after `if`, `for`, `while`, `foreach`, `using`, `try`, etc.). |
| 20 | +- Ensure that the final return statement of a method is on its own line. |
| 21 | +- Use pattern matching and switch expressions wherever possible. |
| 22 | +- Prefer using collection expressions when possible |
| 23 | +- Use `is` pattern matching instead of `as` and null checks |
| 24 | +- Use `nameof` instead of string literals when referring to member names. |
| 25 | +- Prefer `?.` if applicable (e.g. `scope?.Dispose()`). |
| 26 | +- Use `ObjectDisposedException.ThrowIf` where applicable. |
| 27 | +- Use `ArgumentNullException.ThrowIfNull` to validate input paramters. |
| 28 | +- If you add new code files, ensure they are listed in the csproj file (if other files in that folder are listed there) so they build. |
| 29 | + |
| 30 | +### Nullable Reference Types |
| 31 | + |
| 32 | +- Declare variables non-nullable, and check for `null` at entry points. |
| 33 | +- Always use `is null` or `is not null` instead of `== null` or `!= null`. |
| 34 | +- Trust the C# null annotations and don't add null checks when the type system says a value cannot be null. |
| 35 | + |
| 36 | +## Architecture and Design Patterns |
| 37 | + |
| 38 | +### Asynchronous Programming |
| 39 | + |
| 40 | +- Provide both synchronous and asynchronous versions of methods where appropriate. |
| 41 | +- Use the `Async` suffix for asynchronous methods. |
| 42 | +- Return `Task` or `ValueTask` from asynchronous methods. |
| 43 | +- Use `CancellationToken` parameters to support cancellation. |
| 44 | +- Avoid async void methods except for event handlers. |
| 45 | +- Call `ConfigureAwait(false)` on awaited calls to avoid deadlocks. |
| 46 | + |
| 47 | +### Error Handling |
| 48 | + |
| 49 | +- Use appropriate exception types. |
| 50 | +- Include helpful error messages. |
| 51 | +- Avoid catching exceptions without rethrowing them. |
| 52 | + |
| 53 | +### Performance Considerations |
| 54 | + |
| 55 | +- Be mindful of performance implications, especially for database operations. |
| 56 | +- Avoid unnecessary allocations. |
| 57 | +- Consider using more efficient code that is expected to be on the hot path, even if it is less readable. |
| 58 | + |
| 59 | +### Implementation Guidelines |
| 60 | + |
| 61 | +- Write code that is secure by default. Avoid exposing potentially private or sensitive data. |
| 62 | +- Make code NativeAOT compatible when possible. This means avoiding dynamic code generation, reflection, and other features that are not compatible. with NativeAOT. If not possible, mark the code with an appropriate annotation or throw an exception. |
| 63 | + |
| 64 | +## Documentation |
| 65 | + |
| 66 | +- Include XML documentation for all public APIs. Mention the purpose, intent, and 'the why' of the code, so developers unfamiliar with the project can better understand it. If comments already exist, update them to meet the before mentioned criteria if needed. Use the full syntax of XML Doc Comments to make them as awesome as possible including references to types. Don't add any documentation that is obvious for even novice developers by reading the code. |
| 67 | +- Add proper `<remarks>` tags with links to relevant documentation where helpful. |
| 68 | +- For keywords like `null`, `true` or `false` use `<see langword="*" />` tags. |
| 69 | +- Include code examples in documentation where appropriate. |
| 70 | +- Overriding members should inherit the XML documentation from the base type via `/// <inheritdoc />`. |
| 71 | + |
| 72 | +## Markdown |
| 73 | +- Use Markdown for documentation files (e.g., README.md). |
| 74 | +- Use triple backticks for code blocks, JSON snippets and bash commands, specifying the language (e.g., ```csharp, ```json and ```bash). |
| 75 | + |
| 76 | +## Testing |
| 77 | + |
| 78 | +- When adding new unit tests, strongly prefer to add them to existing test code files rather than creating new code files. |
| 79 | +- We use xUnit SDK v3 for tests. |
| 80 | +- Do not emit "Act", "Arrange" or "Assert" comments. |
| 81 | +- Use NSubstitute for mocking in tests. |
| 82 | +- Copy existing style in nearby files for test method names and capitalization. |
| 83 | +- When running tests, if possible use filters and check test run counts, or look at test logs, to ensure they actually ran. |
| 84 | +- Do not finish work with any tests commented out or disabled that were not previously commented out or disabled. |
0 commit comments