Guide to Code Commenting

Code commenting is the practice of sprinkling short, normally single-line notes throughout your code. These notes are called comments. They explain how your program works, and your intentions behind it.

Comments don’t have any effect on your program, but they are invaluable for people reading your code. Here’s an example of code commenting in action:

// increment variable
variable++;

Notice how the comment on the first line describes the line of code below it.

Coders are expected to comment their code to some degree. But if you haven’t been doing so, don’t stress. Learning how to comment your code is not that hard! This guide to code commenting will start you off. We’ll look at the usage and syntax of code comments, as well as two code commenting case studies.

Usage of Code Commenting

Code comments are useful for several purposes. A code comment can…

• explain what a particular function does
• explain something which might not be obvious to the reader
• clarify your intention behind a certain line or block of code
• serve as a reminder to change something in the future.

Code commenting also becomes invaluable when you want to ‘comment out’ code. This is when you turn a block of code into a comment because you don’t want that code to be run, but you still want to keep it on hand in case you want to re-add it.

Code Commenting Syntax

The syntax for code comments differs between coding languages. In many languages, two slashes indicate a single line comment:

// Code Comment

And to include a multi-line comment for when you want to ‘comment out’ code, the syntax is as follows:

/* Commented Out
Commented Out
Commented Out */

The above syntax is used by many languages, such as PHP and JavaScript. However, other languages use different syntax. To verify comment syntax for a particular language, consult the documentation.

Code Commenting Example: Explaining a Function

Unless you’re a crack PHP coder, you’d probably have no idea what the below code does. Or would you? The comment above the function explains what the function does – it checks if input is valid. The comment just saved you from bending over backwards trying to figure out what the function is doing.

// Check if input is valid
function is_valid($first_name, $last_name, $age) {
    if (
        !ctype_alpha($_POST['first_name']) OR
        !ctype_alpha($_POST['last_name']) OR
        !ctype_digit($_POST['age'])
        ) {
        return false;
    }
    return true;
}

I hope you are enjoying this article. To learn more on this topic, you can read this article on what is a good code comment ratio after finishing this one.

Code Commenting Example: Clarifying Your Intention

Consider the below example. If the variable animal is equal to 2, dog() is executed. If it’s equal to 1, cat() is executed, but dog() is executed as well. This is because there’s no break statement at the end of case 1, so that case falls through to the next one.

But is that a mistake or intentional? Unless the comment is included to clarify, there’s no way of knowing whether the coder meant for this to happen or just forgot to include the break statement.

switch(animal) {
    case 1:
        cat();
        // falls through
    case 2:
        dog();
        break;
}

Conclusion

It’s good to get into the habit of adding comments to your code, in case anyone else might ever read it. Even reading it yourself, you’ll find that your comments help to remind you what you were doing with your code.

Being able to comment your code efficiently is an important skill for any coder. In fact, being able to comment code is almost as important as being able to write code. Practice and it’ll soon become second-nature!

Disclosure of Material Connection: Some of the links in the post above are “affiliate links.” This means if you click on the link and purchase the item, I will receive an affiliate commission. Regardless, I only recommend products or services I use personally and believe will add value to my readers.