To comment or to not comment?

Ahmad Muhammad — Mon, 18 Jan 2021 08:46:40 +0000

This is a cross-post from CodeNewbie.

If you're a newbie in the world of programming, you may have heard of comments. Most tutorials aimed towards beginners mention comments, but it can be confusing to figure out exactly where to use them.

What are comments?

Comments are little snippets of information that the programmer can add to their code. Comments are used to make the code easier for humans to understand and are essential when working in teams where there are multiple people working on the same piece of code.
Every programming language has a syntax for adding comments, and any text that goes inside of the comment is ignored by the compiler, allowing you to write whatever you want without breaking your code.

<!-- Comment syntax in HTML -->

/* Comment syntax in CSS */

// Comment syntax in JavaScript; comment ends with line

# Comment syntax in Python; comment ends with line

The above are just a few examples but the concept is the same across programming languages.

What types of comments are there?

There's no set definition on the "types" of comments and most people define them according to personal preference, but within the programming world there are some commonly used types of comments.

Documentation comments

These comments are often found at the beginning of a file, explaining the functionality of the file in basic and human-friendly language. For example:

"""
This file contains various simple mathematical functions for our hypothetical calculator app.
"""
def add(value1, value2):
    first_value = int(value1)
    second_value = int(value2)
    sum = first_value + second_value
    return sum

def subtract(value1, value2):
    first_value = int(value1)
    second_value = int(value2)
    difference = first_value - second_value
    return difference

def multiply(value1, value2):
    first_value = int(value1)
    second_value = int(value2)
    product = first_value * second_value
    return product

def divide(value1, value2):
    first_value = int(value1)
    second_value = int(value2)
    quotient = first_value / second_value
    return quotient

In-line comments

These comments are found in between lines of code, explaining the functionality of a particular snippet or line of code. I'll use our basic math app example again:

# This function takes two values and adds them, then returns the sum. 
def add(value1, value2):
    first_value = int(value1)
    second_value = int(value2)
    sum = first_value + second_value
    return sum

# This function takes two values and subtracts them, then returns the difference. 
def subtract(value1, value2):
    first_value = int(value1)
    second_value = int(value2)
    difference = first_value - second_value # the function doing the arithmetic
    return difference

# This function takes two values and multiplies them, then returns the product. 
def multiply(value1, value2):
    first_value = int(value1)
    second_value = int(value2)
    product = first_value * second_value
    return product

# This function takes two values and divides them, then returns the quotient. 
def divide(value1, value2):
    first_value = int(value1)
    second_value = int(value2)
    quotient = first_value / second_value
    return quotient

You'll also often find comments where programmers leave themselves some information for when they return to their code:

. . .
# This function takes two values and divides them, then returns the quotient. 
def divide(value1, value2):
    first_value = int(value1)
    second_value = int(value2)
    quotient = first_value / second_value
    return quotient

# TODO: ADD FUNCTION TO SQUARE A NUMBER

With that out of the way, it's time to address the biggest question facing new code-writers:

How often should I comment?

Writing clean code that's easy to navigate and easy to understand is just as important as actually writing code itself, if not more. Comments are a useful tool that can help you make your code easy to understand, but like everything it's easy to overdo them. For example, code like this would be classified as not explanatory:

def add(value1, value2):
    first_value = int(value1)
    second_value = int(value2)
    sum = first_value + second_value
    return sum

def subtract(value1, value2):
    first_value = int(value1)
    second_value = int(value2)
    difference = first_value - second_value
    return difference

def multiply(value1, value2):
    first_value = int(value1)
    second_value = int(value2)
    product = first_value * second_value
    return product

def divide(value1, value2):
    first_value = int(value1)
    second_value = int(value2)
    quotient = first_value / second_value
    return quotient

Because this is a simple example, sure it's easy to understand what the code is doing. But pretend that this is a much larger file on a real-world project and you can see why things would get messy real fast. There is no information on what the file is doing, and in a project with tens of files, the functionality of this file wouldn't be self explanatory in most cases. And if our functions were more complex and more in number, it would be really easy to get lost.

However, this:

"""
This file contains various simple mathematical functions for our hypothetical calculator app.
"""
# This function takes two values and adds them, then returns the sum. 
def add(value1, value2): # define the function
    first_value = int(value1) # read the value passed in from the function and assign it to a variable
    second_value = int(value2) # read the value passed in from the function and assign it to a variable
    sum = first_value + second_value # perform the mathematical operation
    return sum # return the result

# This function takes two values and subtracts them, then returns the difference. 
def subtract(value1, value2): # define the function
    first_value = int(value1) # read the value passed in from the function and assign it to a variable
    second_value = int(value2) # read the value passed in from the function and assign it to a variable
    difference = first_value - second_value # perform the mathematical operation
    return difference # return the result

# This function takes two values and multiplies them, then returns the product. 
def multiply(value1, value2): # define the function
    first_value = int(value1) # read the value passed in from the function and assign it to a variable
    second_value = int(value2) # read the value passed in from the function and assign it to a variable
    product = first_value * second_value # perform the mathematical operation
    return product # return the result

# This function takes two values and divides them, then returns the quotient. 
def divide(value1, value2): # define the function
    first_value = int(value1) # read the value passed in from the function and assign it to a variable
    second_value = int(value2) # read the value passed in from the function and assign it to a variable
    quotient = first_value / second_value # perform the mathematical operation
    return quotient # return the result

# TODO: Lorem ipsum....

Is an example of overdoing comments. Unless you're writing a tutorial and want to explain each line of code, the above is simply distracting and not clean. Not to mention a lot of redundant information, since anyone experienced enough to be working on the code knows their way around basic Python functions and the explanation is not needed.

A happy medium solution would be something like this:

"""
This file contains various simple mathematical functions for our hypothetical calculator app.
"""

# This function takes two values and adds them, then returns the sum. 
def add(value1, value2):
    first_value = int(value1)
    second_value = int(value2)
    sum = first_value + second_value
    return sum

# This function takes two values and subtracts them, then returns the difference. 
def subtract(value1, value2):
    first_value = int(value1)
    second_value = int(value2)
    difference = first_value - second_value
    return difference

# This function takes two values and multiplies them, then returns the product. 
def multiply(value1, value2):
    first_value = int(value1)
    second_value = int(value2)
    product = first_value * second_value
    return product

# This function takes two values and divides them, then returns the quotient. 
def divide(value1, value2):
    first_value = int(value1)
    second_value = int(value2)
    quotient = first_value / second_value
    return quotient

There's a basic information about the file at the top, so anyone who's looking for a particular file can see at-a-glance what the file is doing, and there's a short one-liner above each function explaining what the function is doing. Scale the above to a large-scale application and you can imagine for yourself how easy it would be to just skim through this file since you don't have to guess what the code is doing, but at the same time you aren't bombarded with distracting and redundant information.

Another useful method of using comments to make your code cleaner would be to categorize parts of the code. For example:

"""
This file contains various simple mathematical functions for our hypothetical calculator app.
"""

# == ADDITION AND SUBTRACTION ==

# This function takes two values and adds them, then returns the sum. 
def add(value1, value2):
    first_value = int(value1)
    second_value = int(value2)
    sum = first_value + second_value
    return sum

# This function takes two values and subtracts them, then returns the difference. 
def subtract(value1, value2):
    first_value = int(value1)
    second_value = int(value2)
    difference = first_value - second_value
    return difference

# == MULTIPLICATION AND DIVISION ==

# This function takes two values and multiplies them, then returns the product. 
def multiply(value1, value2):
    first_value = int(value1)
    second_value = int(value2)
    product = first_value * second_value
    return product

# This function takes two values and divides them, then returns the quotient. 
def divide(value1, value2):
    first_value = int(value1)
    second_value = int(value2)
    quotient = first_value / second_value
    return quotient

With the above example, adding a new function would be simpler since we can simply add it into the appropriate category. For example, I want to add a function that lets you square a number. with my code categorized I can simply add it like this:

"""
This file contains various simple mathematical functions for our hypothetical calculator app.
"""

# == ADDITION AND SUBTRACTION ==

# This function takes two values and adds them, then returns the sum. 
def add(value1, value2):
    first_value = int(value1)
    second_value = int(value2)
    sum = first_value + second_value
    return sum

# This function takes two values and subtracts them, then returns the difference. 
def subtract(value1, value2):
    first_value = int(value1)
    second_value = int(value2)
    difference = first_value - second_value
    return difference

# == MULTIPLICATION AND DIVISION ==

# This function takes two values and multiplies them, then returns the product. 
def multiply(value1, value2):
    first_value = int(value1)
    second_value = int(value2)
    product = first_value * second_value
    return product

# This function takes a value and squares it, then returns the squared number. 
def square(value):
    first_value = int(value)
    squared = first_value ** 2
    return squared

# This function takes two values and divides them, then returns the quotient. 
def divide(value1, value2):
    first_value = int(value1)
    second_value = int(value2)
    quotient = first_value / second_value
    return quotient

Since squaring a number is a form of multiplication ~~I'm no math major so don't come at me~~ we can easily slide it into its own category as opposed to just adding every new function to the bottom of the list. Anybody who's just browsing through the code knows immediately where everything is and what it's doing, allowing for easy navigation.

In conclusion

Obviously, most of this stuff boils down to circumstances and personal preference. This post merely seeks to act as a guideline, and since it is something that I personally struggled with when starting out, I figured it'd help some people who struggle with the same.
If you have any other suggestions or feedback, I'd love to hear them!

Forem: Ahmad Muhammad