the-standard-code-csharp

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.13.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

0. Follow these rules exactly.
1. Prefer explicit readability over personal taste.
2. Use Standard naming even when team-local habits differ.
3. Reject abbreviations, ambiguous names, noisy wrappers, and inconsistent formatting.
4. Keep methods at level 0 of detail whenever possible.
5. Break down code when chaining or long declarations become cognitively expensive.
6. Preserve property order when instantiating models.
7. Use this. for private fields.
8. 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 ... );

This holds everywhere a lambda parameter appears, including test doubles. A mock setup or verification takes a meaningful name — the type it stands for — never a single letter:

Do

storageBrokerMock.Setup(broker => broker.InsertStudentAsync(student));

Don't

storageBrokerMock.Setup(b => b.InsertStudentAsync(student));

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

A fat-arrow (expression-bodied) method's body must fit on a single line under the arrow. The moment the body needs more than one line — chained calls, or a call whose arguments wrap across several lines — it must use a scoped { } body with an explicit return. Wrapping the method's own parameters across lines does not earn a fat arrow either: if the whole thing does not read as one arrow + one line, scope it.

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);

A call whose arguments wrap across lines is a multi-line body too — scope it, do not fat-arrow it:

Don't

private async ValueTask<TResult> PostAsync<TContent, TResult>(
	string relativeUrl,
	TContent content) =>
	await this.apiClient.PostContentAsync<TContent, TResult>(
		relativeUrl,
		content,
		serializationFunction: async value => Serialize(value),
		deserializationFunction: async json => Deserialize<TResult>(json));

Do

private async ValueTask<TResult> PostAsync<TContent, TResult>(
	string relativeUrl,
	TContent content)
{
	return await this.apiClient.PostContentAsync<TContent, TResult>(
		relativeUrl,
		content,
		serializationFunction: async value => Serialize(value),
		deserializationFunction: async json => Deserialize<TResult>(json));
}

One deliberate exception: a fat arrow whose body is a single call taking a braced lambda keeps the lambda's own { } as its scope, so it stays a fat arrow. This is the TryCatch service pattern, and it is correct:

Do

public ValueTask<Student> AddStudentAsync(Student student) =>
TryCatch(async () =>
{
	ValidateStudent(student);

	return await this.storageBroker.InsertStudentAsync(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

    // ---------------------------------------------------------------
    // Copyright (c) Coalition of the Good-Hearted Engineers
    // FREE TO USE TO CONNECT THE WORLD
    // ---------------------------------------------------------------

Don't

    //----------------------------------------------------------------
    // <copyright file="StudentService.cs" company="OpenSource">
    //      Copyright (C) Coalition of the Good-Hearted Engineers
    // </copyright>
    //----------------------------------------------------------------

Also, Don't

   /* 
    * ==============================================================
    * Copyright (c) Coalition of the Good-Hearted Engineers
    * FREE TO USE TO CONNECT THE WORLD
    * ==============================================================
    */

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

---