Python - Comments

Comments in Python are used to add developer-only text that is not interpreted by the Python interpreter. They allow developers to add notes, explanations, and reminders that are only visible to humans, not to the Python interpreter. In other words, comments are used to describe or explain the code, and they do not interfere with the script's execution.

Comments, in their simplest form, are written by adding # from the point on the line where you want the comment to begin. This means you can write comments on the same line where executable code exists. Lets see some examples,

# This is a comment - it will be ignored by the Python interpreter
print("Hello, World!")  # This is another comment

In the code above, we can clearly see the first line is a full comment, this is because we placed the # as the very first character in the line, this way, any other text that comes after that will be a comment, 

Moving on to the next line where we have print("Hello, World!") # This is another comment , from this line you can clearly see that the #  only comes after the print("Hello, World!")  text, that means the print("Hello, World!") text will be executed by the python interpreter

Multi-Line Comments

We have already seen how we can add simple comments in Python, now lets see how we can add comments to multiple lines. Multi-line comments are especially essential when there is a need to add longer text and format it nicely within the script.

Multi-line comments, in their simplest form, are written by enclosing the comment text within triple quotes (""" """ or ''' '''). This allows you to write comments across multiple lines, making it easier to add longer explanations and well-formatted notes within the script. Lets see some examples,

"""
This is a multi-line comment in Python.
It can be used to explain a block of code,
provide notes, or add detailed descriptions.
"""

website = "PyRepo"
print(website)

From the example above we can clearly see how we can add a multi-line comment in python

What are Comments Used for

In development comments serve several purposes, some of which are listed below:

1. Code explanation: Developers add comments to explain what the code is doing, making it easier for others (and yourself) to understand the logic and intent behind the code (always very important when you visit the code much later).
2. Debugging: One of the most important uses of comments in active development is to temporarily disable parts of the code or to add debugging statements that help identify issues.
3. Documentation: Comments can provide documentation for functions, classes, and modules, making it easier for others to use and understand your code (advanced IDEs like PyCharm can help display the documentation of certain functions, classes, etc., even when you are not actively in the referenced file).

Lets explore all three listed uses with examples

1. Code Explanation with Comments

# Calculate the average score of a student
# The line above is a comment that explains what this whole code does

math_score = 85
english_score = 90
science_score = 88

# Add all scores together  \ This line expains the next line
total = math_score + english_score + science_score

# Divide by the number of subjects
average = total / 3

# Display the final average
print("Average score:", average)

In this example, the comments make the logic easier to follow, especially if you revisit the code months later.

2. Debugging with Comments

Comments are often used to temporarily disable code or add debugging help.

Imagine you are developing a temperature regulation system for a storage facility. The system is programmed to trigger an alarm whenever the temperature rises above 50°C or drops below 5°C.

However, during a period of unstable weather, the temperature starts fluctuating rapidly throughout the day. As a result, the alarm keeps going off repeatedly, becoming more of a disturbance than a useful warning system.

The program itself is still valuable and works correctly, so deleting the code would not be a good idea. Instead, while investigating and debugging the issue, you may temporarily disable the alarm section using comments. This allows the rest of the system to continue running while you test and monitor the temperature behavior safely.

temperature = 52

# Debugging statement to monitor live temperature readings
print("Current temperature:", temperature)

# Alarm system temporarily disabled during testing
# if temperature > 50:
#     print("WARNING: High temperature alarm triggered!")
# elif temperature < 5:
#     print("WARNING: Low temperature alarm triggered!")
# else:
#     print("Temperature is within the safe range.")

print("Alarm system temporarily disabled for debugging.")

In this example:

• The comments temporarily disable the alarm logic.
• The debugging print statement still allows developers to monitor the system.
• Once the issue is resolved, the comments can simply be removed to reactivate the alarm system.

3. Documentation Comments

Comments can document functions, classes, or modules so other developers understand how to use them.

def calculate_area(length, width):
    """
    Calculate the area of a rectangle.

    Parameters:
        length (float): The rectangle's length
        width (float): The rectangle's width

    Returns:
        float: The calculated area
    """

    return length * width


# Using the function
area = calculate_area(5, 3)
print("Area:", area)

This type of documentation is especially useful in IDEs like PyCharm, where hovering over the function can display the explanation automatically.

Comments are an important part of Python programming because they help explain code, simplify debugging, and improve code readability. Although comments are ignored by the Python interpreter, they remain very useful to developers working on the code.