
We all started out programming somewhere. Whether you are a self-taught developer starting out, a computer science major or a 20 year veteran, you all know that even the bad/unreadable code works. In my earlier blog post "[Why Coding Conventions Matter](/posts/why-coding-conventions-matter/)", I talk about writing maintainable and readable code.

There are a number of resources out there about this subject, and I would highly recommend Robert C. Martin's ([Uncle Bob](https://twitter.com/unclebobmartin)) book [Clean Code: A Handbook of Agile Software Craftsmanship](http://a.co/c3mRjVk). And also his website [Clean Coders](https://cleancoders.com/).

# Code Smell

[Code Smell](http://en.wikipedia.org/wiki/Code_smell) is a technical word used to describe the quality of code. Determining what is and is not a code smell is subjective, and varies by language, developer, and development methodology. It is often a word used to describe code that you don't like. In that sense, it is synonymous to ugly, dirty, unclean, repeated...etc.

There are a few reasons why our code smells:
* Duplicated Code
* Methods too big
* Classes with too many instance variables
* Classes with too much code

There is a consensus that clean code can help drive productivity in a software development company. When we are trying to build a prototype, a proof of concept or a minimum viable product, the code may start out as a big jumble mess to get something working but in all cases we should always refactor the code to be maintainable and readable in the end. So what are the characteristics of clean code?

Let's take a look:
* It should be elegant — Clean code should be pleasing to read. Reading it should make you smile.
* Clean code is focused — Classes and functions are [Single responsibility principle](https://en.wikipedia.org/wiki/Single_responsibility_principle)
* Minimize the number of entities such as classes, methods, functions..etc.
* Clean code is taken care of. Someone has taken the time to keep it simple and orderly. They have paid appropriate attention to details. They have cared.
* Contains no duplication of code – [DRY principle](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself)

# How to write clean code?

[![Good Code by XKCD (https://xkcd.com/844/)](/images/good_code.png)](https://xkcd.com/844/)

## Naming Conventions

The name of a variable, function, or class, should answer all the big questions. It should tell you why it exists, what it does, and how it is used. If a name requires a comment, then the name does not reveal its intent. Therefore, name elements on the basis of what they are and make it a habit to maintain a convention throughout your code. Ensure that names are pronounceable.

```csharp
// Bad
DateTime d = DateTime.Now; // current datetime

// Good
DateTime now = DateTime.Now;
```

**Boolean Names** — variables or methods that return a boolean value, should start with "is", "has", "can" or "should"....or something similar to define the yes/no action.

```csharp
// Bad
var admin = identity.IsInRole("Admin");

// Good
var isAdmin = identity.IsInRole("Admin");
```

**Class Names** — Classes and objects should have noun or noun phrase names like Customer, WikiPage, Account, and AddressParser. This also matters on what the intent of the class is. In the [.Net Mvc](https://docs.microsoft.com/en-us/aspnet/core/mvc/overview) world, you would never name your Controllers without containing the word Controller in it like `HomeManager` instead of `HomeController`. Same goes for ViewModels, `ContactData` instead of `ContactViewModel`.

**Interface Names** – Interfaces usually use letter "I" as prefix with name of interface. After letter I, use Pascal case.

```csharp
namespace CleanCode  
{  
    interface IEmployee  
    {  
        void GetDetails();  
    }  
}
```

**Method Names** — Methods should have verb or verb phrase names like PostPayment, DeletePage, or Save. Accessors, mutators, and predicates should be named for their value and prefixed with get, set. Also, methods should be named for what they do, not how they do it. You may change the implementation later and you shouldn’t need to refactor  your consuming code because of it.

```csharp
// Bad
public IEnumerable<Post> GetFromSql()
{
}

// Good
public IEnumerable<Post> GetPosts()
{
}
```

**Pick One Word per Action** — Pick one word for one abstract concept and stick with it. For instance, it’s confusing to have fetch, retrieve, and get as equivalent methods of different classes. How do you remember which method name goes with which class?

**File Names** – Your file names in source code should ideally match your class or entrypoint names. Naming things differently will cause confusion by other contributors of the code. You should always try to strive to keep them in sync.

```csharp
// Bad - BlogPost.cs is named different that class name
public class Post
{
  public int Id { get; set; }
  public string Name { get; set; }
  public int Description { get; set; }
}

// Good - use Post.cs
```

# Methods

The first rule of methods is that they should be small. This implies that the blocks within if statements, else statements, while statements, and so on should be a few lines long. Anything more than a few lines of code results in a high degree of [cyclomatic complexity](https://en.wikipedia.org/wiki/Cyclomatic_complexity). Cyclomatic complexity is a software metric, used to indicate the complexity of a program. The more independent paths the code has, the harder it is to read and therefore debug and maintain.

## Method Arguments

A method shouldn’t have more than 3 to 5 arguments. This definitely isn't a hard number but keep it as low as possible. When a method seems to need more than three  arguments, you probably should wrap the them into a class.

Below, you can see how the code is cleaner buy making a class out of arguments. Not only does it look cleaner, you can now easily refactor the class object without breaking the signature of the method.

```csharp
// Bad
public void Update(int id, string name, string description, string[] tags, string isPublished) 
{
}

// Good
public void Update(Post post)
{
}
```

# Comments

Comments in code may be perceived as problematic. There are instances on when and how to go about commenting your code. Some languages, like c#, allow you to document you code to be exposed for IDEs. There are also tools like [DocFX](https://dotnet.github.io/docfx/), to allow you to generate documentation from source code. This is considered good practice especially when you are writing code that is going to be consumed by other developers.

Add comments only to explain convoluted thoughts. Fewer comments reduces clutter.

```csharp
// Bad
[HttpPost]
public async Task<IActionResult> Create([FromBody] CreatePostViewModel model)
{
  // Check if Model is valid
  if (!ModelState.IsValid)
    return BadRequest(ModelState); // return bad request if not

  try
  {
    // post result from command
    var resultFromCommand = await _mediator.Send(new CreatePostCommand(model));

    // return ok if successful
    return Ok($"Post with Id '{resultFromCommand.Id}' has been created.");
  }
  catch (Exception ex)
  {
    // Add model error and return bad request
    ModelState.AddModelError("", ex.Message);
    return BadRequest(ModelState);
  }
}
```

In the clean version, we rename the result variable to better describe what is returned, thus eliminating the need for comments since the code is self-explanatory.

```csharp
// Good
[HttpPost]
public async Task<IActionResult> Create([FromBody] CreatePostViewModel model)
{
  if (!ModelState.IsValid)
    return BadRequest(ModelState);

  try
  {
    var post = await _mediator.Send(new CreatePostCommand(model));
    return Ok($"Post with Id '{post.Id}' has been created.");
  }
  catch (Exception ex)
  {
    ModelState.AddModelError("Error creating post", ex.Message);
    return BadRequest(ModelState);
  }
}
```

## Clean code doesn't (necessarily) take longer to write

> Clean code always looks like it was written by someone who cares.
>– Michael Feathers

Initially your code may be messy as your starting out with your thoughts and trying to get things to work. You can refactor the code, after it's working, into smaller chunks and fewer lines, each with a single responsibility. Remember, you are writing code not only for yourself but for others that may be supporting your code. 

# Recommended Resources
* [Clean code: A handbook on Agile Software Craftsmanship](https://www.amazon.com/dp/0132350882/ref=cm_sw_r_tw_dp_U_x_dKdVDbW2A3DPW) – Please note that the source code in this book is all in Java. However, you can still benefit from reading this book. This is divided into three parts. The first describes the principles, patterns, and practices of writing clean code. The second part consists of several case studies of increasing complexity. Each case study is an exercise in cleaning up code—of transforming a code base that has some problems into one that is sound and efficient. The third part is the payoff: a single chapter containing a list of heuristics and "smells" gathered while creating the case studies. The result is a knowledge base that describes the way we think when we write, read, and clean code.
* [The Clean Coder](https://www.amazon.com/dp/0137081073/ref=cm_sw_r_tw_dp_U_x_lIdVDbB7MTTGH) – Another book by Uncle Bob. Martin introduces the disciplines, techniques, tools, and practices of true software craftsmanship. This book is packed with practical advice–about everything from estimating and coding to refactoring and testing. It covers much more than technique: It is about attitude. Martin shows how to approach software development with honor, self-respect, and pride; work well and work clean; communicate and estimate faithfully; face difficult decisions with clarity and honesty; and understand that deep knowledge comes with a responsibility to act.
* [Code Complete](https://www.amazon.com/dp/0735619670/ref=cm_sw_r_tw_dp_U_x_CMdVDbSFENXQT) – No matter what your experience level, development environment, or project size, this book will inform and stimulate your thinking — and help you build the highest quality code. 
 

We all started out programming somewhere. Whether you are a self-taught developer starting out, a computer science major or a 20 year veteran, you all know that even the bad/unreadable code works.

Writing clean code


Styles guides document [coding conventions](https://en.wikipedia.org/wiki/Coding_conventions) on topics like class names, variable names and code indentation. It ensures developers write code in a consistent way, making the ability to maintain and read code easier.

When writing code, [style guides](https://en.wikipedia.org/wiki/Programming_style) reduce the number of choices a developer has to make. This allows them to focus on the program's logic instead of making style decisions. They create a consistent look to the code, so that readers can focus on content, not layout. They enable readers to understand the code more quickly by making assumptions based on previous experience. Consistently following the same naming conventions means that you don't need to look up how a property or function name is written. They facilitate copying, changing and maintaining the code.

# Adopting conventions

> The art of programming is the art of organizing complexity, of mastering multitude and avoiding its bastard chaos as effectively as possible.
> — Edsger W. Dijkstra

Conventions are nothing more than standardized work. Bad habits can be formed from various developers when writing their own style code and ignoring decades old good practices and standards, but they all have the same impact: low maintainable and error-prone code. Coding standards can help alleviate poor readability, low productivity, bugs, delays in releases and unmaintainable code. Code which is not readable is code that is more difficult to reuse, extend and evolve.

No one wants to create their own conventions and standards though unless you work for a Google or a Microsoft but luckily almost all programming languages have a consensus on what the best practices are.

Coding style is made up of numerous small decisions based on the language:

* Patterns to be used
* Patterns to be avoided
* How and when to use comments
* Tabs or spaces for indentation (and how many spaces)
* Proper naming of variables and functions

Coding styles can be extremely detailed. Here are some examples such as [Google's Style Guide](https://github.com/google/styleguide), [Microsoft's C# Style Guide](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/inside-a-program/coding-conventions) and [Airbnb React Style Guide](https://github.com/airbnb/javascript/tree/master/react).

# It’s Personal

[![Code Quality 2 by xkcd](/images/coding_conventions_comic.png)](https://xkcd.com/1695/)

The personal nature of coding style is a challenge in a team atmosphere. Some see team-defined style guides as a way of forcing all developers to be the same. Some developers rebel when presented with style guides, believing that they can’t properly do their job if someone is telling them how to write their code.

I think you can relate developing software and programmers to a [concert band](https://en.wikipedia.org/wiki/Concert_band) and musicians. A band will struggle so long as every member is trying to do their own thing. It's impossible to perform great music unless everyone in the band agrees on tempo and style or you have muddle of sounds coming out. Give the musicians a band director, there music will be coordinated and sound much better.

Same holds true for software development and coding conventions. That's why I strongly recommend style guides for software development teams. By having everyone write code that looks the same, you can avoid a lot of problems down the road.

# Fixing Communication

> Programs are meant to be read by humans and only incidentally for computers to execute. — H. Abelson and G. Sussman

The most important thing when working on a team is communication. Coding standards are like speed limits: they are needed but they are useless unless they are respected. While the software your code communicates with doesn't care how the code looks, the other developers on your team certainly do. How many times have you opened up a piece of code that somebody else wrote, and, before doing anything else, re-indented it the way that you like? When everyone is writing code that looks different, everyone is constantly trying to visually parse the code before being able to understand it.

That should be enough to make developers to start thinking of their code as communication to other developers and the code should communicate its purpose to the casual observer. Your code is destined to be maintained by somebody other than you. You're communicating with members of your team in the future.

## Communication in Code Reviews

I think there are guidelines on what code review should accomplish. There are a lot of different ways to approach a code review but most code reviews should verify that the code is a correct and effective solution for the requirements at hand. When reviewing code, you should make sure that it is correct. Check that the code is bug-free, solves the intended problem and handles any edge cases appropriately. Ensure that the code is maintainable, readable and adheres to the style guide. Code reviews also increase shared knowledge of the code base and also style guide as well. This will help sharpen the team's skills through regular feedback.

## Communication in Pair Programming

[Pair programming](https://medium.com/@weblab_tech/pair-programming-guide-a76ca43ff389) is basically a growing software development technique in which two individuals work on the single block of code. The programmers undertake one of two parts — the Driver and the navigator.

The driver in the process is responsible for diligently drafting code, while the navigator’s job is to review and concentrates on the plan of action. Generally the one responsible for typing is known as the 'Driver', while the other one called the 'Navigator' continually revise and review what is being coded or typed. So coding styles can be enforced pair programming and transfer knowledge of coding conventions. The objective is to share the workload between both the participants in order to maintain the constant development stream and also to help spread knowledge over the team.

# Tools

Tools can help enforce coding style. Web developers have an unprecedented number of tools at their fingertips today. Many of them can help ensure that a coding style guide is being followed. These range from command line tools that are run as part of the build, to plugins that work with IDEs. Here are a few tools that can help keep your team on track:

* [JSHint](https://jshint.com/) A JavaScript code quality tool that also checks for stylistic issues.
* [ESLint](https://eslint.org/) A fully pluggable tool for identifying and reporting on patterns in JavaScript
* [CSSLint](https://csslint.net/) A CSS code quality tool by Nicole Sullivan and me that also checks for stylistic issues.
* [SCSSLint](https://github.com/brigade/scss-lint) Configurable tool for writing clean and consistent SCSS
* [TSLint](https://github.com/palantir/tslint) is an extensible static analysis tool that checks TypeScript code for readability, maintainability, and functionality errors
* [ReSharper](https://www.jetbrains.com/resharper/) provides on-the-fly code analysis and eliminates errors in C#, VB.NET, XAML, ASP.NET, XML.
* [StyleCop](https://github.com/DotNetAnalyzers/StyleCopAnalyzers) Analyzers an implementation of the StyleCop rules using the .NET Compiler Platform

# Conclusion

Coding style guides are an important part of writing code as a professional developer. Almost every programming language has some form of one and deciding how your code should look is an important part of overall code quality. If you don’t already have a style guide for your team or project, it’s worth the time to start one. Everyone has to buy in for it to be effective so it's important that everybody on the team participates in it's creation.

Styles guides document coding conventions on topics like class names, variable names and code indentation.

Hi, I'm Michael Baird.

Writing clean code

Why coding conventions matter