Coding Standards

C#

Note

This is not an exhaustive standards document. When in doubt, ask a lead.

Use the explicit type instead of var

Correct

int resultValue = 42;
string title = GetTitle(resultValue);

Incorrect

var resultValue = 42;
var title = GetTitle(resultValue);

Do not use _ for instance variable names

Correct

public class EmployeesController : Controller
{
    private IEmployeeRepository employeeRepository;

    public EmployeesController(IEmployeeRepository employeeRepository)
    {
        this.employeeRepository = employeeRepository ?? throw new ArgumentNullException(nameof(employeeRepository));
    }
}

Incorrect

public class EmployeesController : Controller
{
    private IEmployeeRepository _employeeRepository;

    public EmployeesController(IEmployeeRepository employeeRepository)
    {
        _employeeRepository = employeeRepository ?? throw new ArgumentNullException(nameof(employeeRepository));
    }
}

Use StronglyTypedId for Entity Identifiers

We use the NuGet package StronglyTypedId for entity IDs. Instead of creating an entity with an int, string, or Guid property for its Id, we first create a wrapper type. The author of the library has written a blog post series on why we should do this, so we won’t go into the details why.

Correct

[StronglyTypedId]
public partial struct EmployeeId;

public record Employee(EmployeeId Id);

Incorrect

public record Employee(int Id);

Tip

Put the definition of the EntityId in the same file as the entity itself. See the “correct” example above.

Always use a CancellationToken with async methods

Using a CancellationToken is highly recommended for performance reasons, so we should always use them.

1. When creating an async method, the last argument should be a CancellationToken named cancellationToken.

   Correct

   public Task IEnumerable<Foo> Bar(CancellationToken cancellationToken = default)
   {
       ...
   }

2. When calling a method that accepts a CancellationToken, always give it one.

   Correct

   public async Task<IActionResult> GetAll()
   {
       return this.fooRepository.GetAll(HttpContext.RequestAborted);
   }

   Note

   If you are inside a Controller, you have access to HttpContext.RequestAborted which is a CancellationToken “wired up” to the user’s “stop” button in their browser. This should be passed to any async methods.

   Incorrect

   public async Task<IActionResult> GetAll()
   {
     return this.fooRepository.GetAll(default);
   }

SQL

Table names are always plural

Table names should always be the pluralized version of the noun, e.g. Employees and not Employee.

By convention, in SQL Server, table names are singular. We are bucking the convention and have decided that table names should be plural.

Note

This convention may be overridden on a project level.

Keywords are always all-caps

Keywords in SQL statements should be in all caps so they are easier to see

Correct

INSERT INTO entities (id, name) VALUES (1, 'Test')

Incorrect

insert into entities (id, name) values (1, 'Test')

Correct

SELECT e.FirstName, s.Salary
  FROM Employees e
  JOIN Salaries s ON s.Id = e.SalaryId
 WHERE s.Amount >= 100000

Incorrect

select e.FirstName, s.Salary
  from Employees e
  join Salaries s on s.Id = e.SalaryId
 where s.Amount >= 100000

All constraints should be named

Instead of relying on the database server to generate generic names for your contraints, always explicitly name them.

Correct

CREATE TABLE Employee (
  Id INT NOT NULL
    CONSTRAINT PK_Employee PRIMARY KEY,
  CreatedBy INT NOT NULL
    CONSTRAINT FK_Employee_CreatedBy FOREIGN KEY REFERENCES Users(Id)
)

Incorrect

CREATE TABLE Employee (
  Id INT PRIMARY KEY,
  CreatedBy INT
)