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

gabrielsimas / clean-code-dotnet Goto Github PK