172

I have seen a lot of articles about writing clean code. And that’s good! When I was a teacher, people would ask me what my vision of clean code was. I never understood why people asked about ‘my vision’. I just read about Robert C. Martin, a.k.a. Uncle Bob, and stuck to what I have done and learned.

But some people read a book and follow it as the bible of clean code. I believe there is more to it than just someone telling their best idea of clean code.

My vision of clean code is shaped by my experience and learning from others. I have a few ground ‘rules’ I stick to and try to teach to others who are interested. These are not the only ways to go, and you may not agree with some of them, but I have been using the following tips for many years.

This article is based on C#, but it could also apply to Java, PHP, and other OOP languages.

Team Players

Writing clean code is not a set of rules, like the 10 Commandments. You will discover and develop it as you progress to become a skilled developer. Yes, there are good developers with terrible code who usually don’t work in a team. Because, as a team, you set certain ground rules on how team members should make code. The idea is simple: everyone on the team develops code in the same way, so that everyone can read, change, and build upon it.

We call these ‘rules’ code styles. It’s most of the time a (digital) document that describes what kind of decisions the team has made on certain developing styles.

It can be about anything. Like using var or not, using brackets with a single-lined if statement or not, and declaring variables with capitals, underscores… Or not. Additionally, there are factors such as the maximum number of parameters a method should have.

This way, the team members know how to develop specific codes. Sadly, I have seen this kind of coding style in three out of the 21 companies I have worked for. It usually caused frustration, (unresolved) discussions, and even a fight. Yes, that last one really happened.

So, how do you create a document of coding styles? It starts with the team getting together and discussing the current code. Perhaps some members have questions or disagreements about certain choices made by other members. It’s not a competition about who is right and who is wrong, but rather about bringing the team together in a way that allows everyone to read and understand the code. If two members of the team can’t agree, it’s usually the lead developer who makes the final decision.

Some Rules I Follow

Besides the team, it’s also important for you to make decisions on how to create clean code. If you are working on a project by yourself, you could go with the flow and do whatever seems fit. But what happens if someone comes and helps you? Or if you publish your code online, like in a question or tutorial?

To help you decide on the idea of writing clean code, here are the tips I use.

To var or not to var

I think most developers are familiar with this discussion: Should we use var or explicit declaration? I’ve been using both because my employers asked me to. But when I work on a project by myself, I use var. Yes, past tense.

The var

Using var looks like this:

var someString = "Hello world";
var client = new HttpClient();

The var is an alias of what’s on the right side of the =. In the first line, var is a string. In the second line, ‘var’ is an HTTP client. A big advantage is that you don’t have to type the type twice. So… Var is for lazy people? Nah, it’s just easier. It’s not about being lazy or not. It’s a way of declaring a variable.

Explicit declaration

But it does make the code a little bit harder to read. If you use an explicit declaration on the previous code, it would look like this:

string someString = "Hello world";
HttpClient client = new HttpClient();

In the example above, you can quickly identify the types of variables. This way of declaring a variable is commonly used in example code in tutorials or teaching. Another advantage is that you can now remove the type on the right side and just type ‘new’. For example:

string someString = "Hello world";
HttpClient client = new();

This only works on types that need an initializer.

I used var a lot, but I am using the explicit way more. Why? Because the new way of initializing a type has become more efficient (read: less code), and it’s easier to read. In some cases, I still use var, but that’s limited to unit tests.

Someone told me that using var was insufficient. Because the application needs to convert the variable to its actual type, this is not true; at compile time, the var is being replaced by the exact type, making the var not insufficient when running the application.

Curly Brackets

The use of brackets is well-known in C# and in other languages. It defines a block of code, such as a method, class, or if-statement, and so on. In some cases, you can remove the brackets.

We all know this piece of code:

if(val == "somestring")
{
    Console.WriteLine("Correct!");
}

A simple if-statement with one line within the block. But you can remove the brackets since there is just one line. The advantage is that you reduce the number of brackets, making the code look a bit cleaner, and you can focus more on the code.

if(val == "somestring")
    Console.WriteLine("Correct!");

Bigger example

Maybe the example code does not really show the apparent reason for removing the brackets, so here is a bigger example with brackets:

string greeting = "Hello world";

if(greeting.GetType() == typeof(String))
{
    // Yes this is a string
    Console.WriteLine(greeting);
}
else
{
    Console.WriteLine("This is not a string.");
}

if(greeting.Length > 5)
{
    Console.WriteLine("The length of the greeting exceeds 5 characters.");
}
else
{
    Console.WriteLine(greeting);
}

It’s a simple piece of code of 20 lines. We can reduce the number of lines to 11 by simply removing the brackets:

string greeting = "Hello world";

if(greeting.GetType() == typeof(String))
    Console.WriteLine(greeting);
else
    Console.WriteLine("This is not a string.");

if(greeting.Length > 5)
    Console.WriteLine("The length of the greeting exceeds 5 characters.");
else
    Console.WriteLine(greeting);

A downside

One of the downsides of this is when you add another line to the body of the if-statement. Brackets can be removed when you have just one line. If you add more, you’ll need to add the brackets again.

string greeting = "Hello world";

if(greeting.GetType() == typeof(String))
    Console.WriteLine(greeting);
else
    Console.WriteLine("This is not a string.");
Console.WriteLine("Please use a string"); // This line will always be printed.

if(greeting.Length > 5)
    Console.WriteLine("The length of the greeting exceeds 5 characters.");
else
    Console.WriteLine(greeting);

As you can see, the new line jumps to the left, showing you it’s not a part of the else-statement. The WriteLine of the new line of code will always be executed, even when the greeting is a string.

I am not a fan of brackets as they kinda blur the code. I try to minimize the number of brackets whenever possible. This also helps to notice other refactoring options, as seen in the code above. We can reduce the number of lines even more.

string greeting = "Hello world";

if (greeting.GetType() == typeof(string) && greeting.Length <= 5)
    Console.WriteLine(greeting);
else if (greeting.Length > 5)
    Console.WriteLine("The length of the greeting exceeds 5 characters.");
else
    Console.WriteLine("This is not a string.");

The Green Code: Comments

I already posted a whole blog about comments and how (not) to use them. So here is a small summary.

Don’t use comments

…

Thank you.

Comments can blur the code, making it harder to read. Writing clean code starts with the ability to read the code. The only times one should use comments are:

• When you work on a project alone.
• To write summaries in an interface.
• Explain a challenging calculation.

Don’t use comments to:

• Explain the method.
  Perhaps the name of your method is incorrect.
• To mark a location where you need to do something later.
  Use a scrum board for this.
• Tell your team members to leave the code alone.

Camels And Some Bloke Called Pascal

The way we declare variables, methods, and classes is important. Not only the name but also how we write it. It’s a convention so we can see what a specific name is. Camel and Pascal casing are a big part of this. They define how to use capital letters in a name:

• PascalCasing
• camelCasing

Here, I follow Microsoft’s code conventions, meaning I adhere to their guidelines on when to use Pascal casing and when to use camel casing. There is a whole document you can follow on this topic. But it’s pretty simple:

• Public types are PascalCasing
  This includes, but is not limited to, classes, interfaces, methods, properties, and enums.
• Private types are camelCasing
  This includes, but is not limited to, methods, variables, and private properties.

An example:

namespace ExampleCasing // namespace = PascalCasing
{
    // interface = PascalCasing. Mind the capital I and E.
    public interface IExampleClass 
    {
        string Name { get; set; }
    }

    public class ExampleClass // class = PascalCasing
    {
        public string Name { get; set; } // public property = PascalCasing
        private DateTime currentDateTime; // private class variable = camelCasing
        public ExampleClass() // class = PascalCasing
        {
            string exampleVariable = "Hello world"; // private variable = camelCasing
        }

        private void DoSomething() // private method = camelCasing
        {
            ...
        }
    }

    public enum Gender // enum = PascalCasing
    {
        Male,
        Female,
        Other
    }
}

For those readers who think, “Now I got you!” … Yes, after a chapter about not using comments, I use comments. But I only use them for educational purposes and not in the real code.

Naming conventions

Camel casing and Pascal casing are both parts of the naming convention. But there is more to naming conventions than just these two.

There are a few rules I stick to:

• A name should be short.
  Not like private void ExecuteSQLStatementOnSQLDatabaseThatIsLocatedInAzureWithAConnectionStringInAppSettings()
• A name should be explainable.
  private void Execute() … Execute what?
  private void ExecuteSQLStatement()… Ah, that!
• Only use letters.
  Don’t use numbers, underscores, or other characters. Some are not even allowed. Exception in the unit test methods.
  private void Execute_Sql_Statement().
• Don’t use prefixes on variables
  string sGreeting = “Hello world”;
  string intRating = “1”;
  var lAmount = 1029265527892;

Writing Clean Code Means Keep It Readable

A variable, class, or method name that consists of multiple words should have capitals on each word. For example:

private string helloWorld { get; set; } // Correct; capital W
private string executestatement() // Incorrect. The 's' of statement should be a capital S.
{
    ...
}

public class SomeNewClass // Correct
{

}

The reason why we do this is to make the names more readable. The second method, for example. It’s harder to read since you need to look for the words. The property and the class are easier to read.

Underscores

Microsoft coding conventions dictate that when you have private property on a class, you should add an underscore as a prefix. This is one of the Microsoft ‘rules’ I don’t use. A variable written in camel case indicates that it is private.

public class ExampleClass
{
    private DateTime currentDateTime;
    private string _greetingText;
}

Method Body Size

Some people say a method should be no longer than five rows of code. If that includes the brackets, I don’t know. What I do know is that it’s almost impossible to accomplish this. Yes, you can create hundreds of small methods, but does that help create clean code?

What I try to do is keep my methods between 10 and 20 lines of code, keeping the single responsibility principle in mind: A method or class should have one responsibility. Sometimes I have methods that exceed 20 lines of code, but usually with a good reason. Don’t stress about it too much.

Tip: Start writing code in one method. When everything works like it should, with unit tests, try to break up the method into smaller methods. In the end, you will end up with small methods that are around 10 to 20 lines long.

The Number Of Parameters In Methods

A method can have parameters. I like to keep them to a maximum of 5. If a method receives more parameters, I usually create an object that holds those parameters and uses that single object as a parameter variable.

Some people think three is the max, which is doable. Keep the single responsibility principle in mind. If you put properties together in one single object that have nothing in common, you’ll break that principle.

Counting Characters

Standard practice dictates that lines of code should not exceed the screen. I am really struggling with that one.

What it means is that you don’t scroll left and right in the editor, and you keep all your code in view. This is almost impossible due to the different resolutions of screens. The resolution of my laptop is 1920 x 1080. My desktop PC has two 4K monitors, each with a resolution of 3840 x 2160. However, if someone has a lower resolution, such as 800×600, the code that appears fine on my screen might create a scrollbar on their screen.

Another problem is Visual Studio or different editors in general. Take a look at the screenshot below, which is my Visual Studio.

Everything I need: Editor and Solution Explorer. Other windows, like the SQL browser, GIT, and Error List, are not required all the time, so I minimize or hide them.

No, take a look at the screen of someone who likes to keep track of everything:

Who decides the length of the lines? How many characters are allowed per line? My advice: Keep your editor clean.

Conclusion on Writing Clean Code

These are essentially my ‘rules’ of writing clean code and coding conventions that I strive to follow. Some are easy to follow, while others are not. It all depends on the environment, the job, and the project itself.

Again, these are things I learned during my work and what I have found. You don’t have to agree. If you have any ideas or add-ons, please let me know in the comments.