Skip to content

Commit 69aa765

Browse files
johnwatson484johnwatson484
authored
Modernise .NET and C# standards (#95)
1 parent 4b0fcf5 commit 69aa765

2 files changed

Lines changed: 116 additions & 116 deletions

File tree

‎docs/standards/csharp_coding_standards.md‎

Lines changed: 51 additions & 116 deletions
Original file line numberDiff line numberDiff line change
@@ -1,116 +1,51 @@
1-
# C# coding standards
2-
3-
These are common standards that apply to coding when using C# and are designed to be used in conjunction with the overall common coding standards.
4-
5-
## Rationale
6-
7-
- Ensure consistent C# code and styling across all projects
8-
9-
### Resource
10-
11-
[Microsoft's standard conventions](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/inside-a-program/coding-conventions)
12-
13-
### Naming Conventions
14-
15-
- PascalCasing for class names and method names
16-
17-
```csharp
18-
public class ClientActivity
19-
{
20-
public void ClearStatistics()
21-
{
22-
// ...
23-
}
24-
25-
public void CalculateStatistics()
26-
{
27-
// ...
28-
}
29-
}
30-
```
31-
32-
- camelCasing for method arguments and local variables
33-
34-
```csharp
35-
public class UserLog
36-
{
37-
public void Add(LogEvent logEvent)
38-
{
39-
int itemCount = logEvent.Items.Count;
40-
// ...
41-
}
42-
}
43-
```
44-
45-
- do not use underscores in identifiers (you can prefix private static variables with an underscore)
46-
- use predefined type names instead of system type names for example
47-
48-
```csharp
49-
// Correct
50-
string firstName;
51-
int lastIndex;
52-
53-
// Avoid
54-
String firstName;
55-
Int32 lastIndex;
56-
```
57-
58-
- use noun or noun phrases
59-
60-
```csharp
61-
public class Employee
62-
{
63-
64-
}
65-
66-
public class BusinessLocation
67-
{
68-
69-
}
70-
```
71-
72-
- prefix interfaces with the letter `I`.
73-
74-
```csharp
75-
public interface IShape
76-
{
77-
78-
}
79-
```
80-
81-
### Layout Conventions
82-
83-
[CodeMaid](http://www.codemaid.net/) is a free open source Visual Studio Extension which will cleanup and simplify your C# code. It can be downloaded as an extension to visual studio and can run automatically either on save or on demand on either a selection of code or a whole solution.
84-
85-
1. Remove unused using statements
86-
2. Sort using statements
87-
3. Add unspecified access modifiers
88-
4. Remove empty regions
89-
5. Add blank line padding
90-
6. Remove blank lines next to braces
91-
7. Run Visual Studio formatting
92-
8. Remove consecutive blank lines
93-
9. Remove end of line whitespace
94-
10. Update endregion tags
95-
96-
The default settings for CodeMaid should remain in place to adhere to [DEFRA principles](../principles/README.md) (details at http://www.codemaid.net/documentation/)
97-
98-
### Testing
99-
100-
As per the general coding standards it is expected that 90% of code is covered with unit tests however given unit test coverage in some C# projects (i.e. MVC) will include coverage of default Microsoft template code this 90% figure can be misleading. It is not expected that unit tests should be written to cover code already written by Microsoft and therefore attributes can be added to this code to exclude them from the code coverage calculation.
101-
102-
For example in a typical MVC application exclusions can be applied to areas such as anything in `App_Start` folder, any migrations, `global.asax`, etc.
103-
104-
To exclude test code from the code coverage results and only include application code, add the `ExcludeFromCodeCoverageAttribute` attribute to your test class.
105-
106-
To customize code coverage, follow these steps:
107-
108-
1. Add a run settings file to your solution. In Solution Explorer, on the shortcut menu of your solution, choose Add > New Item, and select XML File. Save the file with a name such as `CodeCoverage.runsettings`.
109-
2. Add the content from the [example file](https://docs.microsoft.com/en-us/visualstudio/test/customizing-code-coverage-analysis?view=vs-2017#sample-runsettings-file), and then customize it to your needs as described in the sections that follow.
110-
3. To select the run settings file, on the Test menu, choose Test Settings > Select Test Settings File. To specify a run settings file for running tests from the command line or in a build workflow, see Configure unit tests by using a `.runsettings` file.
111-
112-
When you select Analyze Code Coverage, the configuration information is read from the run settings file.
113-
114-
To turn the custom settings off and on, deselect or select the file in the Test > Test Settings menu.
115-
116-
https://docs.microsoft.com/en-us/visualstudio/test/customizing-code-coverage-analysis?view=vs-2017
1+
# C# Standards
2+
3+
This document outlines the standards for writing C# code at Defra. To ensure consistency and maintainability, we align with Microsoft's official C# standards and best practices.
4+
5+
## Key Principles
6+
7+
1. **Alignment with Microsoft Standards**:
8+
- Follow Microsoft's official C# coding conventions for:
9+
- Naming conventions
10+
- Indentation
11+
- Code formatting
12+
- Linting
13+
- Refer to the following resources:
14+
- [C# Coding Conventions](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/coding-conventions)
15+
- [Framework Design Guidelines](https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/)
16+
17+
2. **Modern C# Practices**:
18+
- Use modern C# features such as:
19+
- `async`/`await` for asynchronous programming.
20+
- Nullable reference types (`string?`) to avoid null reference exceptions.
21+
- Pattern matching for cleaner and more readable code.
22+
- Records for immutable data models.
23+
- Avoid outdated practices and legacy patterns unless required for compatibility.
24+
25+
3. **SOLID Principles**:
26+
- Follow the **SOLID principles** to ensure your code is maintainable, scalable, and easy to understand. These principles are:
27+
- **S - Single Responsibility Principle (SRP)**:
28+
- A class should have only one reason to change. Each class should focus on a single responsibility or functionality.
29+
- **O - Open/Closed Principle (OCP)**:
30+
- Classes should be open for extension but closed for modification. This allows new functionality to be added without altering existing code.
31+
- **L - Liskov Substitution Principle (LSP)**:
32+
- Subtypes must be substitutable for their base types without altering the correctness of the program.
33+
- **I - Interface Segregation Principle (ISP)**:
34+
- A class should not be forced to implement interfaces it does not use. Large interfaces should be split into smaller, more specific ones.
35+
- **D - Dependency Inversion Principle (DIP)**:
36+
- High-level modules should not depend on low-level modules. Both should depend on abstractions, often achieved through dependency injection.
37+
38+
For a detailed explanation of the issues with violating SOLID principles, refer to [Microsoft's overview](https://learn.microsoft.com/en-us/archive/msdn-magazine/2014/may/csharp-best-practices-dangers-of-violating-solid-principles-in-csharp).
39+
40+
4. **Testing**:
41+
- Write unit tests for all business logic.
42+
- Use mocking frameworks for dependency isolation.
43+
- Focus on meaningful code coverage rather than arbitrary metrics.
44+
45+
## Additional Resources
46+
47+
For further guidance, refer to the following Microsoft resources:
48+
- [C# Language Reference](https://learn.microsoft.com/en-us/dotnet/csharp/)
49+
- [Asynchronous Programming in C#](https://learn.microsoft.com/en-us/dotnet/csharp/async)
50+
- [Secure Coding Guidelines for .NET](https://learn.microsoft.com/en-us/dotnet/standard/security/secure-coding-guidelines)
51+
- [Common Web Application Architectures in .NET](https://learn.microsoft.com/en-us/dotnet/architecture/modern-web-apps-azure/common-web-application-architectures) (for general C# architecture guidance)

‎docs/standards/net_standards.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# .NET Standards
2+
3+
At Defra, we use .NET as a secondary technology stack, with **Node.js** being our primary stack.
4+
5+
.NET does not align with our recruitment or training strategies and has a significantly smaller talent pool within Defra compared to Node.js.
6+
7+
The use of .NET must be justified with an **evidence-based decision**. This document outlines the standards for using .NET within Defra, ensuring alignment with modern practices and Microsoft's best practices.
8+
9+
## Key Principles
10+
11+
1. **Primary Stack Preference**:
12+
- **Node.js** is the preferred stack for all new projects.
13+
- The decision to use .NET must be supported by clear evidence, such as:
14+
- Integration with commodity products or libraries that are best suited to .NET.
15+
- Specific backend service requirements that are better suited to .NET.
16+
- Ecosystem is already heavily invested in .NET, making it more efficient to continue using it.
17+
- Matches team profile and expertise.
18+
- .NET is more prone to state mutation through multi-threading which can lead to hard to debug issues.
19+
20+
2. **Backend Services Only**:
21+
- .NET is only used for **backend services** and **integration with commodity products**.
22+
- **Frontend applications** must not be developed using .NET.
23+
24+
3. **C# Language**:
25+
- All .NET development must use the **C# language**.
26+
- Refer to the [C# Standards](csharp_coding_standards.md) for language-specific guidelines.
27+
28+
4. **Long-Term Support (LTS)**:
29+
- Always strive to use the latest **LTS version** of .NET.
30+
- **.NET Framework** should only be used for maintaining legacy applications.
31+
32+
## When to use .NET over Node.js
33+
34+
While Node.js is the preferred stack, there are scenarios where .NET may be better suited:
35+
36+
1. **Integration with Microsoft Ecosystem**:
37+
- Some parts of the Microsoft ecosystem are easier to integrate with when using .NET. For example:
38+
- Dynamics 365, which has strong support for .NET libraries and SDKs.
39+
40+
2. **High-Performance Backend Services**:
41+
- .NET is generally better suited for CPU-intensive operations, such as:
42+
- Complex mathematical computations.
43+
- Image or video processing.
44+
- Real-time data analysis.
45+
- The Just-In-Time (JIT) compilation and runtime optimizations in .NET can outperform Node.js in these scenarios.
46+
47+
3. **Large-Scale Multi-Layer Monolith**:
48+
- For large-scale, multi-layered monolithic applications that require:
49+
- Clear separation of concerns (e.g., presentation, business logic, and data access layers).
50+
- Advanced tooling for debugging and profiling.
51+
- .NET provides a robust framework and ecosystem to support such architectures effectively.
52+
53+
4. **Cross-Platform Desktop Applications**:
54+
- If backend services need to complement cross-platform desktop applications built with .NET technologies like:
55+
- WPF (Windows Presentation Foundation).
56+
- WinForms.
57+
- MAUI (Multi-platform App UI).
58+
- .NET ensures seamless integration between the desktop and backend.
59+
60+
## Best practices
61+
62+
To ensure consistency and maintainability, follow Microsoft's official guidelines for .NET development:
63+
- [Microsoft .NET Documentation](https://learn.microsoft.com/en-us/dotnet/)
64+
- [Best Practices for .NET Applications](https://learn.microsoft.com/en-us/dotnet/architecture/modern-web-apps-azure/)
65+
- [Secure Coding Guidelines for .NET](https://learn.microsoft.com/en-us/dotnet/standard/security/secure-coding-guidelines)

0 commit comments

Comments
 (0)