Quick Tips For Writing Clean Code - Part Two

This blog aims at writing clean code and avoiding some common mistakes that programmers usually make while writing code.

This is in continuation to the Quick Tips for writing Clean Code Part-1 and in this blog, we will be discussing the below points:

Comments

1. Redundant Comment
2. Intent Comment
3. Apology Comment
4. Warning Comment
5. Zombie Code
6. Divider Comment

So, the first thing to keep in mind while writing comments is to use comments only when your code alone isn't sufficient.

We should always prefer code over comments and write code in a way which is self-expressive and clear in intent.

Redundant Comment

public class User {
    private DateTime _dateOfBirth;
    //Constructor
    public User(DateTime dateOfBirth) {
        _dateOfBirth = dateOfBirth;
    }
    //This method is used to calculate age
    public int CalculateAge() {
        return DateTime.Now.Year - _dateOfBirth.Year;
    }
    //This method is used to get the date of birth
    public string GetDOB(string formatter) {
        return _dateOfBirth.ToString(formatter);
    }
}

The problem with repeated comments is that they violate the DRY principle and really add no value.

So, it’s not necessary to add a comment for a method if your method is named well.

void Main() {
    var counter = 1; // Set the counter to 1
    var user = new User(new DateTime(1988, 10, 9));
    user.CalculateAge().Dump();
    user.GetDOB("dddd, dd MMMM yyyy HH:mm:ss").Dump();
    user.GetDOB("dd/MM/yyyy").Dump();
}

OUTPUT

Intent Comment

Rather than mentioning intent using comments try to clarify the intent of the code in the code itself like using

• Improved function names.
• Constants or enum.
• Intermediate variables etc.

Apology Comment

Don’t ever write such apologetic comments. Always fix it before you push the code, or you can also add a TODO marker comment.

Warning Comment

If one sees any comments such as

which are alarming or giving warning signals then go ahead and refactor the code and make it clean so that next time you or someone else visits the code, he should not be looking at those warning comments.

Zombie Code

Zombie code is a code which is not runnable as it is commented, and it is also not dead as you keep seeing it whenever you come to the place where it has been written.

void Main() {
    var counter = 1; // Set the counter to 1
    var user = new User(new DateTime(1988, 10, 9));
    user.CalculateAge().Dump();
    //  user.GetDOB("dddd, dd MMMM yyyy HH:mm:ss").Dump();
    //  user.GetDOB("dd/MM/yyyy").Dump();
}

As a programmer it’s our responsibility to clean the zombie code wherever we find it. If you don’t know what it does then go and discuss this code with some of your seniors and after mutual discussion just throw it out of the repo.

SAY NO TO ZOMBIE CODE.

Zombie code has several ill effects some of which are

• Less readability.
• Ambiguity and confusion.
• Hinders refactoring.

With source control in place, the code is not lost anywhere, and we can always track it.

Divider Comment

If you see divider comments in your code, then it is a clear indication that your code needs refactoring.

public void myLongMethod() {
    //Start - Get Data
    //........ ... .......//
    //....... CODE GOES HERE ....... //
    //........ ... .......//
    //End - Get Data
    //Start - Performing operations
    //........ ... .......//
    //....... CODE GOES HERE ....... //
    //........ ... .......//
    //End - operations
}

THINKING OF WRITING A COMMENT?

Ask yourself, can I express the intent in the code itself with a better name, by using an intermediate variable or using an enum or by avoiding magic numbers etc.?

Comments are useful but for clean codes, it’s their last resort.

Cheers to Coding!!