| name | The Standard Code CSharp |
| description | Enforces the C# naming, organization, method, variable, class, field, instantiation, and comment/documentation rules of The Standard. |
| the standard version | v2.12.0 |
| skill version | v0.3.0.0 |
The Standard Code CSharp
What this skill is
This skill is the canonical C# coding-style and organization layer for The Standard.
Use it whenever generating, reviewing, refactoring, or evaluating C# code.
Explicit coverage map
This skill explicitly covers all supplied C# style rule files:
- Files
- Variables
- Methods
- Classes and Interfaces
- Comments and Documentation
It also preserves the implementation-profile naming conventions supplied in the implementation specification.
When to use
Use this skill for any C# or .NET code, including models, brokers, services, controllers, tests, and support code.
Mandatory operating behavior
- Follow these rules exactly.
- Prefer explicit readability over personal taste.
- Use Standard naming even when team-local habits differ.
- Reject abbreviations, ambiguous names, noisy wrappers, and inconsistent formatting.
- Keep methods at level 0 of detail whenever possible.
- Break down code when chaining or long declarations become cognitively expensive.
- Preserve property order when instantiating models.
- Use
this. for private fields.
- Maintain partial-file conventions for multi-dimensional classes.
Canonical rule set
0 Files
The following are the naming conventions and guidance for naming C# files.
0.0 Naming
File names should follow the PascalCase convention followed by the file extension .cs.
Do
Student.cs
Also, Do
StudentService.cs
Don't
student.cs
Also, Don't
studentService.cs
Also, Don't
Student_Service.cs
0.1 Partial Class Files
Partial class files are files that contain nested classes for a root file. For instance:
- StudentService.cs
- StudentService.Validations.cs
- StudentService.Exceptions.cs
Both validations and exceptions are partial classes to display a different aspect of any given class in a multi-dimensional space.
Do
StudentService.Validations.cs
Also, Do
StudentService.Validations.Add.cs
Don't
StudentServiceValidations.cs
Also, Don't
StudentService_Validations.cs
0. Variables
0.0 Naming
Variable names should be concise and representative of nature and the quantity of the value it holds or will potentially hold.
0.0.0 Names
Do
var student = new Student();
Don't
var s = new Student();
Also, Don't
var stdnt = new Student();
The same rule applies to lambda expressions:
Do
students.Where(student => student ... );
Don't
students.Where(s => s ... );
0.0.1 Plurals
Do
var students = new List<Student>();
Don't
var studentList = new List<Student>();
0.0.2 Names with Types
Do
var student = new Student();
Don't
var studentModel = new Student();
Also, Don't
var studentObj = new Student();
0.0.3 Nulls or Defaults
If a variable value is it's default such as 0 for int or null for strings and you are not planning on changing that value (for testing purposes for instance) then the name should identify that value.
Do
Student noStudent = null;
Don't
Student student = null;
Also, Do
int noChangeCount = 0;
But, Don't
int changeCount = 0;
0.1 Declarations
Declaring a variable and instantiating it should indicate the immediate type of the variable, even if the value is to be determined later.
0.1.0 Clear Types
If the right side type is clear, then use var to declare your variable
Do
var student = new Student();
Don't
Student student = new Student();
0.1.1 Semi-Clear Types
If the right side isn't clear (but known) of the returned value type, then you must explicitly declare your variable with it's type.
Do
Student student = GetStudent();
Don't
var student = GetStudent();
0.1.2 Unclear Types
If the right side isn't clear and unknown (such as an anonymous types) of the returned value type, you may use var as your variable type.
Do
var student = new
{
Name = "Hassan",
Score = 100
};
0.1.3 Single-Property Types
Assign properties directly if you are declaring a type with one property.
Do
var inputStudentEvent = new StudentEvent();
inputStudentEvent.Student = inputProcessedStudent;
Don't
var inputStudentEvent = new StudentEvent
{
Student = inputProcessedStudent
};
Also, Do
var studentEvent = new StudentEvent
{
Student = someStudent,
Date = someDate
}
Don't
var studentEvent = new StudentEvent();
studentEvent.Student = someStudent;
studentEvent.Date = someDate;
0.2 Organization
0.2.0 Breakdown
If a variable declaration exceeds 120 characters, break it down starting from the equal sign.
Do
List<Student> washingtonSchoolsStudentsWithGrades =
await GetAllWashingtonSchoolsStudentsWithTheirGradesAsync();
Don't
List<Student> washgintonSchoolsStudentsWithGrades = await GetAllWashingtonSchoolsStudentsWithTheirGradesAsync();
0.2.1 Multiple Declarations
Declarations that occupy two lines or more should have a new line before and after them to separate them from previous and next variables declarations.
Do
Student student = GetStudent();
List<Student> washingtonSchoolsStudentsWithGrades =
await GetAllWashingtonSchoolsStudentsWithTheirGradesAsync();
School school = await GetSchoolAsync();
Don't
Student student = GetStudent();
List<Student> washgintonSchoolsStudentsWithGrades =
await GetAllWashingtonSchoolsStudentsWithTheirGradesAsync();
School school = await GetSchoolAsync();
Also, declarations of variables that are of only one line should have no new lines between them.
Do
Student student = GetStudent();
School school = await GetSchoolAsync();
Don't
Student student = GetStudent();
School school = await GetSchoolAsync();
1 Methods
1.0 Naming
Method names should be a summary of what the method is doing, it needs to stay percise and short and representative of the operation with respect to synchrony.
1.0.0 Verbs
Method names must contain verbs in them to represent the action it performs.
Do
public List<Student> GetStudents()
{
...
}
Don't
public List<Student> Students()
{
...
}
1.0.1 Asynchronousy
Asynchronous methods should be postfixed by the term Async such as methods returning Task or ValueTask in general.
Do
public async ValueTask<List<Student>> GetStudentsAsync()
{
...
}
Don't
public async ValueTask<List<Student>> GetStudents()
{
...
}
1.0.2 Input Parameters
Input parameters should be explicit about what property of an object they will be assigned to, or will be used for any action such as search.
Do
public async ValueTask<Student> GetStudentByNameAsync(string studentName)
{
...
}
Don't
public async ValueTask<Student> GetStudentByNameAsync(string text)
{
...
}
Also, Don't
public async ValueTask<Student> GetStudentByNameAsync(string name)
{
...
}
1.0.3 Action Parameters
If your method is performing an action with a particular parameter specify it.
Do
public async ValueTask<Student> GetStudentByIdAsync(Guid studentId)
{
...
}
Don't
public async ValueTask<Student> GetStudentAsync(Guid studentId)
{
...
}
1.0.4 Passing Parameters
When utilizing a method, if the input parameters aliases match the passed in variables in part or in full, then you don't have to use the aliases, otherwise you must specify your values with aliases.
Assume you have a method:
Student GetStudentByNameAsync(string studentName);
Do
string studentName = "Todd";
Student student = await GetStudentByNameAsync(studentName);
Also, Do
Student student = await GetStudentByNameAsync(studentName: "Todd");
Also, Do
Student student = await GetStudentByNameAsync(toddName);
Don't
Student student = await GetStudentByNameAsync("Todd");
Don't
Student student = await GetStudentByNameAsync(todd);
1.1 Organization
In general encapsulate multiple lines of the same logic into their own method, and keep your method at level 0 of details at all times.
1.1.0 Single/Multiple-Liners
1.1.0.0 One-Liners
Any method that contains only one line of code should use fat arrows
Do
public List<Student> GetStudents() => this.storageBroker.GetStudents();
Don't
public List<Student> Students()
{
return this.storageBroker.GetStudents();
}
If a one-liner method exceeds the length of 120 characters then break after the fat arrow with an extra tab for the new line.
Do
public async ValueTask<List<Student>> GetAllWashingtonSchoolsStudentsAsync() =>
await this.storageBroker.GetStudentsAsync();
Don't
public async ValueTask<List<Student>> GetAllWashingtonSchoolsStudentsAsync() => await this.storageBroker.GetStudentsAsync();
1.1.0.1 Multiple-Liners
If a method contains multiple liners separated or connected via chaining it must have a scope. Unless the parameters are going on the next line then a one-liner method with multi-liner params is allowed.
Do
public Student AddStudent(Student student)
{
ValidateStudent(student);
return this.storageBroker.InsertStudent(student);
}
Also, Do
public Student AddStudent(Student student)
{
return this.storageBroker.InsertStudent(student)
.WithLogging();
}
Also, Do
public Student AddStudent(
Student student)
{
return this.storageBroker.InsertStudent(student);
}
Don't
public Student AddStudent(Student student) =>
this.storageBroker.InsertStudent(student)
.WithLogging();
Also, Don't
public Student AddStudent(
Student student) =>
this.storageBroker.InsertStudent(student);
1.1.1 Returns
For multi-liner methods, take a new line between the method logic and the final return line (if any).
Do
public List<Student> GetStudents()
{
StudentsClient studentsApiClient = InitializeStudentApiClient();
return studentsApiClient.GetStudents();
}
Don't
public List<Student> GetStudents()
{
StudentsClient studentsApiClient = InitializeStudentApiClient();
return studentsApiClient.GetStudents();
}
1.1.2 Multiple Calls
With mutliple method calls, if both calls are less than 120 characters then they may stack unless the final call is a method return, otherwise separate with a new line.
Do
public List<Student> GetStudents()
{
StudentsClient studentsApiClient = InitializeStudentApiClient();
List<Student> students = studentsApiClient.GetStudents();
return students;
}
Don't
public List<Student> GetStudents()
{
StudentsClient studentsApiClient = InitializeStudentApiClient();
List<Student> students = studentsApiClient.GetStudents();
return students;
}
Also, Do
public async ValueTask<List<Student>> GetStudentsAsync()
{
StudentsClient washingtonSchoolsStudentsApiClient =
await InitializeWashingtonSchoolsStudentsApiClientAsync();
List<Student> students = studentsApiClient.GetStudents();
return students;
}
Don't
public async ValueTask<List<Student>> GetStudentsAsync()
{
StudentsClient washingtonSchoolsStudentsApiClient =
await InitializeWashingtonSchoolsStudentsApiClientAsync();
List<Student> students = studentsApiClient.GetStudents();
return students;
}
1.1.3 Declaration
A method declaration should not be longer than 120 characters.
Do
public async ValueTask<List<Student>> GetAllRegisteredWashgintonSchoolsStudentsAsync(
StudentsQuery studentsQuery)
{
...
}
Don't
public async ValueTask<List<Student>> GetAllRegisteredWashgintonSchoolsStudentsAsync(StudentsQuery studentsQuery)
{
...
}
1.1.4 Multiple Parameters
If you are passing multiple parameters, and the length of the method call is over 120 characters, you must break by the parameters, with one parameter on each line.
Do
List<Student> redmondHighStudents = await QueryAllWashingtonStudentsByScoreAndSchoolAsync(
MinimumScore: 130,
SchoolName: "Redmond High");
Don't
List<Student> redmondHighStudents = await QueryAllWashingtonStudentsByScoreAndSchoolAsync(
MinimumScore: 130,SchoolName: "Redmond High");
1.1.5 Chaining (Uglification/Beautification)
Some methods offer extensions to call other methods. For instance, you can call a Select() method after a Where() method. And so on until a full query is completed.
We will follow a process of Uglification Beautification. We uglify our code to beautify our view of a chain methods. Here's some examples:
Do
students.Where(student => student.Name is "Elbek")
.Select(student => student.Name)
.ToList();
Don't
students
.Where(student => student.Name is "Elbek")
.Select(student => student.Name)
.ToList();
The first approach enforces simplifying and cutting the chaining short as more calls continues to uglify the code like this:
students.SomeMethod(...)
.SomeOtherMethod(...)
.SomeOtherMethod(...)
.SomeOtherMethod(...)
.SomeOtherMethod(...);
The uglification process forces breaking down the chains to smaller lists then processing it. The second approach (no uglification approach) may require additional cognitive resources to distinguish between a new statement and an existing one as follows:
student
.Where(student => student.Name is "Elbek")
.Select(student => student.Name)
.OrderBy(student => student.Name)
.ToList();
ProcessStudents(students);
4 Classes
4.0 Naming
Classes that represent services or brokers in a Standard-Compliant architecture should represent the type of class in their naming convention, however that doesn't apply to models.
4.0.0 Models
Do
class Student {
...
}
Don't
class StudentModel {
}
4.0.1 Services
In a singular fashion, for any class that contains business logic.
Do
class StudentService {
....
}
Don't
class StudentsService{
...
}
Also, Don't
class StudentBusinessLogic {
...
}
Also, Don't
class StudentBL {
...
}
4.0.2 Brokers
In a singular fashion, for any class that is a shim between your services and external resources.
Do
class StudentBroker {
....
}
Don't
class StudentsBroker {
...
}
4.0.3 Controllers
In a plural fashion, to reflect endpoints such as /api/students to expose your logic via RESTful operations.
Do
class StudentsController {
....
}
Don't
class StudentController {
...
}
4.1 Fields
A field is a variable of any type that is declared directly in a class or struct. Fields are members of their containing type.
4.1.0 Naming
Class fields are named in a camel cased fashion.
Do
class StudentsController {
private readonly string studentName;
}
Don't
class StudentController {
private readonly string StudentName;
}
Also, Don't
class StudentController {
private readonly string _studentName;
}
Should follow the same rules for naming as mentioned in the Variables sections.
4.1.1 Referencing
When referencing a class private field, use this keyword to distinguish private class member from a scoped method or constructor level variable.
Do
class StudentsController {
private readonly string studentName;
public StudentsController(string studentName) {
this.studentName = studentName;
}
}
Don't
class StudentController {
private readonly string _studentName;
public StudentsController(string studentName) {
_studentName = studentName;
}
}
4.2 Instantiations
4.2.0 Input Params Aliases
If the input variables names match to input aliases, then use them, otherwise you must use the aliases, especially with values passed in.
Do
int score = 150;
string name = "Josh";
var student = new Student(name, score);
Also, Do
var student = new Student(name: "Josh", score: 150);
But, Don't
var student = new Student("Josh", 150);
Also, Don't
Student student = new (...);
4.2.1 Honoring Property Order
When instantiating a class instance - make sure that your property assignment matches the properties order in the class declarations.
Do
public class Student
{
public Guid Id {get; set;}
public string Name {get; set;}
}
var student = new Student
{
Id = Guid.NewGuid(),
Name = "Elbek"
}
Also, Do
public class Student
{
private readonly Guid id;
private readonly string name;
public Student(Guid id, string name)
{
this.id = id;
this.name = name;
}
}
var student = new Student (id: Guid.NewGuid(), name: "Elbek");
Don't
public class Student
{
public Guid Id {get; set;}
public string Name {get; set;}
}
var student = new Student
{
Name = "Elbek",
Id = Guid.NewGuid()
}
Also, Don't
public class Student
{
private readonly Guid id;
private readonly string name;
public Student(string name, Guid id)
{
this.id = id;
this.name = name;
}
}
var student = new Student (id: Guid.NewGuid(), name: "Elbek");
Also, Don't
public class Student
{
private readonly Guid id;
private readonly string name;
public Student(Guid id, string name)
{
this.id = id;
this.name = name;
}
}
var student = new Student (name: "Elbek", id: Guid.NewGuid());
12 Comments
12.0 Introduction
Comments can only be used to explain what code can't. Whether the code is visible or not.
12.1 Copyrights
Comments highlighting copyrights should follow this pattern:
Do
Don't
Also, Don't
12.2 Methods
Methods that have code that is not accessible at dev-time, or perform a complex function should contain the following details in their documentation.
- Purposing
- Incomes
- Outcomes
- Side Effects
Implementation-profile naming addendum
10. Naming Conventions
| Element | Pattern | Example |
|---|
| Broker interface | I{Resource}Broker | IStorageBroker, IModernApiBroker, ILoggingBroker |
| Broker class | {Resource}Broker | StorageBroker, ModernApiBroker, LoggingBroker |
| Broker method | {Action}{Entity}Async | InsertLegacyUserAsync, PostPersonAsync |
| Service interface | I{Entity}Service | ILegacyUserService |
| Service class | {Entity}Service | LegacyUserService |
| Service method | Add{Entity}Async | AddLegacyUserAsync |
| Inner exception | {Adjective}{Entity}Exception | NullLegacyUserException |
| Outer exception | {Entity}{Category}Exception | LegacyUserValidationException |
| Test class | {Entity}ServiceTests | LegacyUserServiceTests |
| Test method | Should{Action}Async / ShouldThrow{Exception}On{Action}… | ShouldAddLegacyUserAsync |
