Comments are essential for writing clear, maintainable, and well-documented code. They help developers explain the purpose, logic, or behavior of specific sections of code. By using comments effectively, you make your code easier to understand for others and for yourself when revisiting it later.

Table of Contents

1. What Are Comments in Python?
2. Types of Comments in Python
3. How to Write Comments
4. Best Practices for Writing Comments
5. Common Mistakes to Avoid with Comments
6. Mini-Project: Adding Comments to a Simple Program
7. Interview Questions and Answers

1. What Are Comments in Python?

Comments are lines in a Python program that are ignored by the Python interpreter. They are used purely for documentation purposes and do not affect the program’s execution.

2. Types of Comments in Python

Python supports two types of comments:

1. Single-line Comments: Use the # symbol for comments on a single line.
2. Multi-line Comments: Use triple quotes (''' or """) for comments that span multiple lines, though they are often used for docstrings.

3. How to Write Comments

Single-line Comments:

Use the # symbol at the beginning of the line.

# This is a single-line comment
print("Hello, World!")  # Inline comment

Multi-line Comments:

Use triple quotes for multi-line comments. While they are technically treated as strings, they are often used to explain complex logic or provide detailed descriptions.

"""
This is a multi-line comment.
It is often used for documentation.
"""

4. Best Practices for Writing Comments

• Be Clear and Concise: Use simple language to explain your code.
• Explain the Why, Not the What: Focus on why the code exists, not just what it does (the code itself explains the “what”).
• Avoid Over-Commenting: Write comments only where necessary; don’t clutter the code with obvious explanations.
• Keep Comments Updated: Update comments whenever you modify the associated code.
• Use Docstrings for Functions and Classes: Document their purpose, arguments, and return values.

Example of a function with a docstring:

def add_numbers(a, b):
    """
    Adds two numbers and returns the result.
    
    Args:
    a (int): The first number.
    b (int): The second number.
    
    Returns:
    int: The sum of a and b.
    """
    return a + b

5. Common Mistakes to Avoid with Comments

• Writing Vague Comments: Avoid comments like # This line does something. Be specific.
• Leaving Outdated Comments: Update comments when changing the code to prevent confusion.
• Over-Commenting: Don’t write comments for obvious code.

Bad Example:

x = 10  # Assigns 10 to x

Good Example:

x = 10  # Represents the initial count of items

6. Mini-Project: Adding Comments to a Simple Program

Here’s a simple program to calculate the factorial of a number. Let’s add meaningful comments to explain each step.

def factorial(n):
    """
    Calculates the factorial of a given number.

    Args:
    n (int): The number to calculate the factorial for.

    Returns:
    int: The factorial of the number.
    """
    if n == 0 or n == 1:  # Base case: factorial of 0 or 1 is 1
        return 1
    else:
        result = 1
        for i in range(2, n + 1):  # Loop through numbers from 2 to n
            result *= i  # Multiply result by the current number
        return result  # Return the final factorial value

print(factorial(5))  # Example: Calculate the factorial of 5

Interview Questions and Answers

Google

• Q: Why are comments important?
  A: Comments make the code more readable and easier to understand, especially for other developers or when revisiting code after a long time.

Amazon

• Q: Can comments impact the execution of a program?
  A: No, comments are ignored by the interpreter and do not affect program execution.

TCS

• Q: What is the best way to document a function in Python?
  A: Use a docstring with triple quotes inside the function to describe its purpose, arguments, and return value.

Infosys

• Q: How do you write multi-line comments in Python?
  A: You can use triple quotes (''' or """) to write comments that span multiple lines.

Zoho

• Q: What is a common mistake when writing comments?
  A: A common mistake is leaving outdated comments that no longer match the updated code, leading to confusion.

Conclusion

Using comments effectively is a vital skill for writing clean, maintainable code. By adhering to best practices, you can ensure that your code remains understandable, well-documented, and accessible for future use.

Comments

Start Quiz

Question

Your answer:

Correct answer:

Next

You got {{SCORE_CORRECT}} out of {{SCORE_TOTAL}}

Your Answers