|
| 1 | +## Coding Guidelines |
1 | 2 | - Rules apply to our C# code.
|
2 | 3 | - Use function-reflective, descriptive names without implementation details.
|
| 4 | +- Avoid magic strings and numbers; use constants or configuration. |
3 | 5 | - For multi-task methods, use descriptive names and document the process.
|
4 | 6 | - Long method names are acceptable.
|
| 7 | +- Prefer async/await over Task.Result or .Wait() |
5 | 8 | - Async methods must have an "Async" suffix.
|
| 9 | +- Use cancellation tokens for async operations when appropriate |
6 | 10 | - Avoid using booleans solely to signal success, unless failure is an expected frequent outcome (e.g. TryGet methods).
|
7 | 11 | - Do not return null unless explicitly indicated (e.g., TryCreate).
|
8 | 12 | - Validate early; if validation fails, throw or return immediately.
|
|
11 | 15 | - Use immutable objects (e.g., records, readonly properties) when possible.
|
12 | 16 | - Never throw generic Exceptions.
|
13 | 17 | - Use structural logging consistently.
|
14 |
| -- Each method should log its own actions. |
| 18 | +- Each method should log its own actions. |
| 19 | +- Use nullable reference types and annotate appropriately. |
| 20 | +- Follow the AAA (Arrange-Act-Assert) pattern for unit tests. |
| 21 | +- Prefer ILogger<T> over ILogger for better context in logs. |
| 22 | +- Services should be registered with appropriate lifetimes (singleton, scoped, transient). |
| 23 | + |
| 24 | +## Repository Structure |
| 25 | +- `docs/` - Documentation |
| 26 | +- `eng/` - Engineering scripts, build tools and pipeline templates |
| 27 | +- `src/` - Contains the main source code for arcade services |
| 28 | +- `test/` - Test projects and test utilities |
| 29 | +- `Microsoft.DotNet.Darc/` - Darc CLI tool for interacting with dependency management services |
| 30 | + |
| 31 | +## Key Technologies |
| 32 | +- .NET 8 |
| 33 | +- Azure DevOps APIs |
| 34 | +- ASP.NET Core for web APIs |
| 35 | +- Entity Framework Core for data access |
| 36 | +- Azure Container Apps for hosting |
| 37 | +- .NET Aspire for local development |
| 38 | + |
| 39 | +## Development Environment |
| 40 | +- You can restore required .NET and dependencies by calling: |
| 41 | + - `./eng/common/build.sh -restore` on Linux/macOS |
| 42 | + - `.\eng\common\build.ps1 -restore` on Windows |
0 commit comments