How to Comment Your Code Like a Pro

Hello guys, I am back with another article that I think will be super useful for any programmer, especially for someone who is a beginner to the field. Without further ado, let’s get into it.

Nowadays, everyone is talking about writing quality code. Well as programmers, we know from experience that there is no such thing as perfect code. Because your code works properly even after doing 1000 test runs, doesn’t necessarily mean that your code is bug-free. Actually, there is a basic concept in quality assurance saying exactly that.

The best thing you could do is writing a quality flexible easy to understand code solution. Commenting your code properly is a must-have skill you need to have in your skill repertoire in order to write a quality code solution.

In my opinion, basically, there are 3 occasions where you should add comments in your code.

At the beginning of a class

/**
 * Class description goes here
 *
 * @version 1.0 05/04/2020
 * @author firstname lastname
 */

Add a simple document comment like shown in the picture. You can always modify the comment to anything you want. But always try to keep it simple and clear as it will be easier for someone else to understand the purpose of creating the class.

At the beginning of a method

/**
     * Adds two integers and return the total
     *
     * @param num1 - int
     * @param num2 - int
     * @return total - int
     * @author Thisura Thenuka 05/04/2020
     */
    public static int addNumbers(int num1, int num2){
        return num1 + num2;
    }

I added the data type of the parameters to make it more clear for someone who reads it.

To clarify a piece of code

/* Checking if the total is odd or even and logging to the console */
        if (total % 2 == 0) {
            System.out.println("Entered number is even");
        } else {
            System.out.println("Entered number is odd");
        }

You can use comments anywhere to clarify a piece of code. As long as it is brief and clear, you are good to go.

Avoid These Things

Never Use Comments like This

Image Source – Fortune.com

Don’t add unnecessary comments

int age = 10; //Assigning 10 to age

This is just useless. This is just going to ruin the clarity of the code.

Be professional

//What is this? This code sucks. Go and learn the basics first, Drake

Never write comments like this. I have seen this mostly in open source projects. You would feel like you are releasing your frustration. But you are going to look like a fool. Learn to manage your anger and instead write a comment like this.

//The code below is not up to the standard.
//I commented that piece of code and added my own code

Well, that’s it for today guys. Thank you for reading the article. If you learned something valuable, go ahead and subscribe to get an email when I upload a new article. Have a nice day and stay safe ❤✌

Published by Thisura Thenuka

I am a passionate software engineering student. But cricket is my first love ❤

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: