clean-code-dotnet

Introduction
Naming
Variables
Functions
Objects and Data Structures
Classes
SOLID
Testing
Concurrency
Error Handling
Formatting
Comments

Introduction

Software engineering principles, from Robert C. Martin's book Clean Code, adapted for .NET and .NET Core. This is not a style guide. It's a guide to producing readable, reusable, and refactorable software in .NET and .NET Core.

Not every principle herein has to be strictly followed, and even fewer will be universally agreed upon. These are guidelines and nothing more, but they are ones codified over many years of collective experience by the authors of Clean Code.

Inspired from clean-code-javascript and clean-code-php

Naming

Naming it hard and it takes time but worth it. Choosing good names takes time but saves more than it takes and it will help everyone who reads your code (including you) will be happier if you do. Naming should reflect about what it does, what is the context.

Bad:

int d;

Good:

int daySinceModification;

Avoid Disinformation name

Programmers must avoid naming with disinformation name and we should name variable to reflect what we want to do with it.

Bad:

var dataFromDb = db.GetFromService().Tolist();

Good:

var listOfEmployee = _employeeService.GetEmployeeListFromDb().Tolist();

Use Pronounceable Names

What happends if we cant pronoun variables, function, etc... It will take us a lot of time (some time make us like an idiot to discuss about it) to investigate what meaning of that variables, what is use.

Bad:

public class Employee {
    public Datetime sWorkDate { get; set; } // what the heck is this
    public Datetime modTime { get; set; } // same here
}

Good:

public class Employee {
    public Datetime startWorkingDate { get; set; }
    public Datetime modificationTime { get; set; }
}

Use Hungarian Notation

Use Hungarian Notation for variable and parms function

Bad:

var employeephone // or var employee-phone

public double CalculateSalary(int workingdays, int workinghours)
{
    // some logic
}

Good:

var employeePhone // or var employee-phone

public double CalculateSalary(int workingDays, int workingHours)
{
    // some logic
}

Use domain name

People who read your code is also programmers. So naming right will help everyone on the same page because we dont want to take time to explain for everyone what that variable for, what the function for. We can name the variable or function to reflect the pattern, algorithm names and so forth.

Good

public class SingleObject {
   //create an object of SingleObject
   private static SingleObject instance = new SingleObject();

   //make the constructor private so that this class cannot be
   //instantiated
   private SingleObject(){}

   //Get the only object available
   public static SingleObject GetInstance(){
      return instance;
   }

   public string ShowMessage(){
      return "Hello World!";
   }
}

public static void main(String[] args) {

      //illegal construct
      //SingleObject object = new SingleObject();

      //Get the only object available
      SingleObject singletonObject = SingleObject.GetInstance();

      //show the message
      singletonObject.ShowMessage();
}

Variables

Use meaningful and pronounceable variable names 📄

Bad:

var ymdstr = DateTime.UtcNow.ToString("MMMM dd, yyyy");

Good:

var currentDate = DateTime.UtcNow.ToString("MMMM dd, yyyy");

⬆ Back to top

Use the same vocabulary for the same type of variable 📄

Bad:

GetUserInfo();
GetUserData();
GetUserRecord();
GetUserProfile();

Good:

GetUser();

⬆ Back to top

Use searchable names (part 1) 📄

We will read more code than we will ever write. It's important that the code we do write is readable and searchable. By not naming variables that end up being meaningful for understanding our program, we hurt our readers. Make your names searchable.

Bad:

// What the heck is data for?
var data = new { Name = "John", Age = 42 };

var stream1 = new MemoryStream();
DataContractJsonSerializer ser1 = new DataContractJsonSerializer(typeof(object));
ser1.WriteObject(stream1, data);

stream1.Position = 0;
var sr1 = new StreamReader(stream1);
Console.Write("JSON form of Data object: ");
Console.WriteLine(sr1.ReadToEnd());

Good:

var person = new Person
{
    Name = "John",
    Age = 42
};

var stream2 = new MemoryStream();
DataContractJsonSerializer ser2 = new DataContractJsonSerializer(typeof(Person));
ser2.WriteObject(stream2, data);

stream2.Position = 0;
StreamReader sr2 = new StreamReader(stream2);
Console.Write("JSON form of Data object: ");
Console.WriteLine(sr2.ReadToEnd());

Use searchable names (part 2) 📄

Bad:

var data = new { Name = "John", Age = 42, PersonAccess = 4};

// What the heck is 4 for?
if (data.PersonAccess == 4)
{
    // do edit ...
}

Good:

public enum PersonAccess : int
{
    ACCESS_READ = 1,
    ACCESS_CREATE = 2,
    ACCESS_UPDATE = 4,
    ACCESS_DELETE = 8
}

var person = new Person
{
    Name = "John",
    Age = 42,
    PersonAccess= PersonAccess.ACCESS_CREATE
};

if (person.PersonAccess == PersonAccess.ACCESS_UPDATE)
{
    // do edit ...
}

⬆ Back to top

Use explanatory variables 📄

Bad:

const string Address = "One Infinite Loop, Cupertino 95014";
var cityZipCodeRegex = @"/^[^,\]+[,\\s]+(.+?)\s*(\d{5})?$/";
var matches = Regex.Matches(Address, cityZipCodeRegex);
if (matches[0].Success == true && matches[1].Success == true)
{
    SaveCityZipCode(matches[0].Value, matches[1].Value);
}

Good:

Decrease dependence on regex by naming subpatterns.

const string Address = "One Infinite Loop, Cupertino 95014";
var cityZipCodeWithGroupRegex = @"/^[^,\]+[,\\s]+(?<city>.+?)\s*(?<zipCode>\d{5})?$/";
var matchesWithGroup = Regex.Match(Address, cityZipCodeWithGroupRegex);
var cityGroup = matchesWithGroup.Groups["city"];
var zipCodeGroup = matchesWithGroup.Groups["zipCode"];
if(cityGroup.Success == true && zipCodeGroup.Success == true)
{
    SaveCityZipCode(cityGroup.Value, zipCodeGroup.Value);
}

hiepngovan/clean-code-dotnet

clean-code-dotnet

Table of Contents

Introduction

Naming

Avoid Disinformation name

Use Pronounceable Names

Use Hungarian Notation

Use domain name

Variables

Use meaningful and pronounceable variable names 📄

Use the same vocabulary for the same type of variable 📄

Use searchable names (part 1) 📄

Use searchable names (part 2) 📄

Use explanatory variables 📄

Avoid nesting too deeply and return early 📄

Avoid Mental Mapping 📄

Don't add unneeded context 📄

Use default arguments instead of short circuiting or conditionals 📄

Avoid magic string

Functions

Function arguments (2 or fewer ideally)

Functions should do one thing

Function names should say what they do

Functions should only be one level of abstraction

Don't use flags as function parameters

Avoid Side Effects

Don't write to global functions

Don't use a Singleton pattern

Encapsulate conditionals

Avoid negative conditionals

Avoid conditionals

Avoid type-checking (part 1)

Avoid type-checking (part 2)

Remove dead code

Objects and Data Structures

Use getters and setters

Make objects have private/protected members

Classes

Use method chaining

Prefer composition over inheritance

SOLID

Single Responsibility Principle (SRP)

Open/Closed Principle (OCP)

Liskov Substitution Principle (LSP)

Interface Segregation Principle (ISP)

Dependency Inversion Principle (DIP)

Don’t repeat yourself (DRY)

Testing

Single concept per test

Concurrency

Use Promises, not callbacks

Async/Await are even cleaner than Promises

Error Handling

Don't ignore caught errors

Don't ignore rejected promises

Formatting

Use consistent capitalization

Function callers and callees should be close

Comments

Only comment things that have business logic complexity.

Don't leave commented out code in your codebase

Don't have journal comments

Avoid positional markers