Lesson: Understanding and Using Comments in Python

Introduction

People create notes and reminders for themselves all the time. When you need to buy groceries, you look through your cabinets, determine what you need, and write it down on a list. When you get to the store, you review your list to remember what you need.

Using notes comes in handy for all sorts of needs, such as tracking the course of a conversation between business partners or remembering the essential points of a lecture. Humans need notes to jog their memories.

Comments in Programming

Comments in source code are just another form of note. You add them to the code so that you can remember what task the code performs later.

Computers need a special way to determine that the text you’re writing is a comment, not code to execute. Python provides two methods of defining text as a comment and not as code.

Single-Line Comments

The first method is the single-line comment. It uses the number sign #, like this:

# This is a comment
print("Hello from Python!") # This is also a comment.

A single-line comment can appear on a line by itself or after executable code. It appears on only one line. You typically use a single-line comment for short descriptive text, such as an explanation of a particular bit of code.

Examples of Single-Line Comments

# Number of apples in the basket
apples = 10

# Function to add two numbers
def add(a, b):
    return a + b

# TODO: Optimize this algorithm
for i in range(1000):
    print(i)

Multi-Line Comments

When you need to create a longer comment, you use a multi-line comment. A multi-line comment starts and ends with three double quotes """, like this:

"""
Application: Adding Python Comments.py
Written by: Bernard Aybout
Purpose: Shows how to use comments in Python.
"""

Everything between the two sets of triple-double quotes is considered a comment. You typically use multi-line comments for longer explanations of who created an application, why it was created, and what tasks it performs. There aren’t any hard rules on precisely how you use comments. The main goal is to tell the computer precisely what is and isn’t a comment so that you don’t get any errors.

Examples of Multi-Line Comments

"""
Function: calculate_area
Parameters:
    radius (float): The radius of the circle
Returns:
    float: The area of the circle
Description:
    This function calculates the area of a circle
    using the formula: area = π * radius^2.
"""
def calculate_area(radius):
    return 3.14159 * radius ** 2

"""
Module: math_operations.py
Author: Bernard Aybout
Date: 2024-05-25
Description:
    This module contains basic mathematical operations
    such as addition, subtraction, multiplication, and division.
"""

"""
This block of code implements the sorting algorithm.
It uses a combination of quicksort and mergesort to achieve
optimal performance for different sizes of input arrays.
"""
def complex_sort(arr):
    # Sorting logic here
    pass

Benefits of Using Comments

Using comments to leave yourself reminders is crucial. You might write a piece of code today and then not look at it for a long time. You need notes to jog your memory so that you remember what task the code performs and why you wrote it. Here are some common reasons to use comments in your code:

• Reminding yourself of what the code does and why you wrote it: Comments help you understand the purpose and functionality of the code when you revisit it later.
• Telling others how to maintain your code: Comments guide other developers on how to handle and maintain your code.
• Making your code accessible to other developers: Clear comments make it easier for others to understand and work with your code.
• Listing ideas for future updates: Use comments to note down potential improvements or features you want to add later.
• Providing a list of documentation sources you used to write the code: This can be helpful for reference and validation.
• Maintaining a list of improvements you’ve made: Track changes and enhancements directly within your code.

Commenting Out Code

Developers also sometimes use the commenting feature to keep lines of code from executing, referred to as commenting out. You might need to do this to determine whether a line of code is causing your application to fail. For example:

# print("This line is commented out and won't execute")
print("This line will execute")

Commenting out lines of code can help in debugging by isolating problematic sections of code without deleting them.

Examples of Commenting Out Code

# print("Debugging output 1")
print("Debugging output 2")

# Feature disabled for maintenance
# enable_feature_x()

# if condition_met():
#     execute_action()
print("Action not executed")

Conclusion

Comments are an essential part of writing clean, maintainable code. They serve as reminders and guides, helping both you and other developers understand the code better. By using single-line and multi-line comments effectively, you can ensure that your code is well-documented and easier to work with. Remember, the goal of comments is to improve the readability and maintainability of your code, making it accessible and understandable for anyone who may work on it in the future.