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.
- 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.
- 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.
- 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.
- 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.
- 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.
No comments:
Post a Comment