C# Coding Standards Best Practices

As a developer, it's essential to adhere to coding standards and best practices to ensure that your code is readable, maintainable, and efficient. In this blog post, we will discuss Microsoft C# coding standards and best practices.

Naming conventions: 

C# has several naming conventions that developers should follow to make their code more readable. The conventions are as follows:

• Use PascalCase for class names and method names.
• Use camelCase for parameter names and variable names.
• Use all caps for constant names.
• Use an underscore prefix for private fields.

Code formatting: 

Formatting your code correctly can improve its readability. Here are a few best practices for formatting your C# code:

• Use four spaces for indentation.
• Use braces to delimit blocks of code.
• Place each block of code on a new line.
• Use parentheses to group expressions.

Comments: 

Comments are an essential part of any codebase. Here are a few best practices for using comments in your C# code:

• Use XML comments to document your code.
• Use comments sparingly to explain why your code is doing something.
• Avoid commenting out code; instead, use version control to track changes.

Error handling: 

Exception handling is a critical aspect of any C# application. Here are a few best practices for handling errors in your code:

• Catch specific exceptions rather than using a catch-all block.
• Log error messages to help diagnose issues.
• Handle exceptions as close to the source of the problem as possible.

Performance: 

Writing efficient code is essential for ensuring that your application performs well. Here are a few best practices for improving the performance of your C# code:

• Use foreach loops rather than for loops.
• Use StringBuilder to concatenate strings.
• Avoid using string concatenation in loops.
• Avoid using unnecessary object creation.

The following are the naming conventions and guidance for naming C# files.

Naming

File names should follow the PascalCase convention followed by the file extension `.cs`.

 

Do	Don't
Student.cs	student.cs
StudentService.cs	studentService.cs
	Student_Service.cs

2. 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	Don't
StudentService.Validations.cs	StudentServiceValidations.cs
StudentService.Validations.Add.cs	StudentService_Validations.cs

Comments

Comments can only be used to explain what code can't. Whether the code is visible or not.

Copyrights

Comments highlighting copyrights should follow this pattern:

 

Do	Don't
// ---------------------------------------------------------------     // Copyright (c) name     // FREE TO USE TO CONNECT THE WORLD     // ---------------------------------------------------------------	//----------------------------------------------------------------     // <copyright file="StudentService.cs" company="OpenSource">     //      Copyright (C) name     // </copyright>     //----------------------------------------------------------------
/*     * ==============================================================     * Copyright (c) name     * FREE TO USE TO CONNECT THE WORLD     * ==============================================================     */ ```	/*     * ==============================================================     * Copyright (c) name     * FREE TO USE TO CONNECT THE WORLD     * ==============================================================     */

 

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

III. Classes

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.

Do	Don't
class Student {             ... }	class StudentModel {   } <br />

Services

In a singular fashion, for any class that contains business logic.

 

Do	Don't
class StudentService {             .... }	class StudentsService{             ... }
	class StudentBusinessLogic {             ... }
	class StudentBL {             ... } <br />

 Brokers

In a singular fashion, for any class that is a shim between your services and external resources.

 

Do	Don't
class StudentBroker {             .... } ```	class StudentsBroker {             ... } ``` <br />

 Controllers

In a plural fashion, to reflect endpoints such as ```/api/students``` to expose your logic via RESTful operations.

 

Do	Don't
class StudentsController {             .... } ```	class StudentController {             ... } ```  <br /> <br />

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.

Naming

Class fields are named in a camel cased fashion.

 

Do	Don't
class StudentsController {             private readonly string studentName; } ```	class StudentController {             private readonly string StudentName; } ```
	class StudentController {             private readonly string _studentName; } ``` Should follow the same rules for naming as mentioned in the Variables sections. <br />

Referencing

When referencing a class private field, use ```this``` keyword to distinguish private class member from a scoped method or constructor level variable.

 

Do	Don't
class StudentsController {             private readonly string studentName;                         public StudentsController(string studentName) {                         this.studentName = studentName;             } }	class StudentController {             private readonly string _studentName;               public StudentsController(string studentName) {                         _studentName = studentName;             } } ``` <br /> <br />

 Instantiations

 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	Don't
int score = 150; string name = "Josh";  var student = new Student(name, score); ```	var student = new Student("Josh", 150);   ```
var student = new Student(name: "Josh", score: 150);  ```	Student student = new (...); ```

 Honoring Property Order

When instantiating a class instance - make sure that your property assignment matches the properties order in the class declarations.

Do	Don't
public class Student {             public Guid Id {get; set;}             public string Name {get; set;} }   var student = new Student {             Id = Guid.NewGuid(),             Name = "Elbek" }	public class Student {             public Guid Id {get; set;}             public string Name {get; set;} }   var student = new Student {             Name = "Elbek",             Id = Guid.NewGuid() }
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");	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");
	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());

IV.Methods

 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.

 Verbs

Method names must contain verbs in them to represent the action it performs.

 

Do	Don't
public List<Student> GetStudents() {             ... }   ```	public List<Student> Students() {             ... } ``` <br />

 Asynchronousy

Asynchronous methods should be postfixed by the term ```Async``` such as methods returning ```Task``` or ```ValueTask``` in general.

 

Do	Don't
public async ValueTask<List<Student>> GetStudentsAsync() {             ... } ```	public async ValueTask<List<Student>> GetStudents() {             ... } ``` <br />

 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	Don't
public async ValueTask<Student> GetStudentByNameAsync(string studentName) {             ... } ```	public async ValueTask<Student> GetStudentByNameAsync(string text) {             ... } ```
	public async ValueTask<Student> GetStudentByNameAsync(string name) {             ... } ``` <br />

 Action Parameters

If your method is performing an action with a particular parameter specify it.

 

Do	Don't
public async ValueTask<Student> GetStudentByIdAsync(Guid studentId) {             ... } ```	public async ValueTask<Student> GetStudentAsync(Guid studentId) {             ... } ``` <br />

 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:

```csharp

Student GetStudentByNameAsync(string studentName);

```

Do	Don't
string studentName = "Todd"; Student student = await GetStudentByNameAsync(studentName);  ```	Student student = await GetStudentByNameAsync("Todd"); ```
Student student = await GetStudentByNameAsync(studentName: "Todd"); ```	Student student = await GetStudentByNameAsync(todd); ```  <br /><br />
Student student = await GetStudentByNameAsync(toddName); ```

 

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.

One-Liners

Any method that contains only one line of code should use fat arrows

 

Do	Don't
public List<Student> GetStudents() => this.storageBroker.GetStudents();   ```	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	Don't
public async ValueTask<List<Student>> GetAllWashingtonSchoolsStudentsAsync() =>             await this.storageBroker.GetStudentsAsync(); ```	public async ValueTask<List<Student>> GetAllWashingtonSchoolsStudentsAsync() => await this.storageBroker.GetStudentsAsync(); ``` <br />

 Returns

For multi-liner methods, take a new line between the method logic and the final return line (if any).

Do	Don't
public List<Student> GetStudents(){             StudentsClient studentsApiClient = InitializeStudentApiClient();               return studentsApiClient.GetStudents(); } ```	public List<Student> GetStudents(){             StudentsClient studentsApiClient = InitializeStudentApiClient();             return studentsApiClient.GetStudents(); } ``` <br />

 

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	Don't
public List<Student> GetStudents(){             StudentsClient studentsApiClient = InitializeStudentApiClient();             List<Student> students = studentsApiClient.GetStudents();               return students; }	public List<Student> GetStudents(){             StudentsClient studentsApiClient = InitializeStudentApiClient();              List<Student> students = studentsApiClient.GetStudents();              return students; } ```
public List<Student> GetStudents(){             StudentsClient washingtonSchoolsStudentsApiClient =                         await InitializeWashingtonSchoolsStudentsApiClientAsync();               List<Student> students = studentsApiClient.GetStudents();               return students; }	public List<Student> GetStudents(){             StudentsClient washingtonSchoolsStudentsApiClient =                         await InitializeWashingtonSchoolsStudentsApiClientAsync();             List<Student> students = studentsApiClient.GetStudents();               return students; } ``` <br />

Declaration

A method declaration should not be longer than 120 characters.

Do	Don't
public async ValueTask<List<Student>> GetAllRegisteredWashgintonSchoolsStudentsAsync(             StudentsQuery studentsQuery) {             ... } ```	public async ValueTask<List<Student>> GetAllRegisteredWashgintonSchoolsStudentsAsync(StudentsQuery studentsQuery) {             ... } ``` <br />

 

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	Don't
List<Student> redmondHighStudents = await QueryAllWashingtonStudentsByScoreAndSchoolAsync(             MinimumScore: 130,             SchoolName: "Redmond High"); ```	List<Student> redmondHighStudents = await QueryAllWashingtonStudentsByScoreAndSchoolAsync(             MinimumScore: 130,SchoolName: "Redmond High"); ```

 

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	Don't
students.Where(student => student.Name is "Elbek")                         .Select(student => student.Name)                                     .ToList(); ```	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:

 ```csharp

            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:

```csharp

            student

            .Where(student => student.Name is "Elbek")

            .Select(student => student.Name)

            .OrderBy(student => student.Name)

            .ToList();

            ProcessStudents(students);

```

V.Variables

Naming

Variable names should be concise and representative of nature and the quantity of the value it holds or will potentially hold.

 

Do	Don't
var student = new Student(); ```	var s = new Student(); ```
	var stdnt = new Student(); ```

 The same rule applies to lambda expressions:

 

Do	Don't
students.Where(student => student ... ); ```	students.Where(s => s ... ); ``` <br />

 Plurals

Do	Don't
var students = new List<Student>(); ```	var studentList = new List<Student>(); ``` <br />

 Names with Types

Do	Don't
var student = new Student(); ```	var studentModel = new Student(); ```
	var studentObj = new Student(); ``` <br />

 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	Don't
Student noStudent = null; ```	Student student = null; ```
int noChangeCount = 0; ```	int changeCount = 0; ``` <br /> <br />

 Declarations

Declaring a variable and instantiating it should indicate the immediate type of the variable, even if the value is to be determined later.

Clear Types

If the right side type is clear, then use ```var``` to declare your variable

 

Do	Don't
var student = new Student(); ```	Student student = new Student(); ``` <br /> <br />

 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	Don't
Student student = GetStudent(); ```	var student = GetStudent(); ``` <br />

 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

};

```

<br /> <br />

 Single-Property Types

 Assign properties directly if you are declaring a type with one property.

 

Do	Don't
var inputStudentEvent = new StudentEvent(); inputStudentEvent.Student = inputProcessedStudent; ```	var inputStudentEvent = new StudentEvent {     Student = inputProcessedStudent }; ```
var studentEvent = new StudentEvent {     Student = someStudent,     Date = someDate } ```	var studentEvent = new StudentEvent(); studentEvent.Student = someStudent; studentEvent.Date = someDate; ```

 Organization

 Breakdown

If a variable declaration exceeds 120 characters, break it down starting from the equal sign.

 

Do	Don't
List<Student> washingtonSchoolsStudentsWithGrades =     await GetAllWashingtonSchoolsStudentsWithTheirGradesAsync();   ```	List<Student> washgintonSchoolsStudentsWithGrades = await GetAllWashingtonSchoolsStudentsWithTheirGradesAsync(); ``` <br />

 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	Don't
Student student = GetStudent();   List<Student> washingtonSchoolsStudentsWithGrades =     await GetAllWashingtonSchoolsStudentsWithTheirGradesAsync();   School school = await GetSchoolAsync(); ```	Student student = GetStudent(); List<Student> washgintonSchoolsStudentsWithGrades =     await GetAllWashingtonSchoolsStudentsWithTheirGradesAsync(); School school = await GetSchoolAsync(); ```
Student student = GetStudent(); School school = await GetSchoolAsync(); ```	Student student = GetStudent();   School school = await GetSchoolAsync();   ``` <br />

 

Also, declarations of variables that are of only one line should have no new lines between them.