Python Comments Tutorial: Single-line, Multi-line & Docstrings

Comments in Python are lines of text within your code that are ignored by the Python interpreter. They are non-executable statements meant to provide explanations, documentation, or clarifications to yourself and other developers who might read your code.

Types of Comments

1. Single-line Comments:
   • Start with a hash symbol (#).
   • Everything after the # on that line is considered a comment.
   Python# This is a single-line comment print("Hello, world!") # This is also a comment
2. Multi-line Comments (Docstrings):
   • Enclosed in triple quotes ("""Docstring goes here""").
   • Used for documenting functions, classes, and modules.
   • Can span multiple lines.
   Pythondef my_function(): """This is a docstring that explains what the function does.""" # Code implementation goes here

Uses of Comments

• Explanation: Explain the purpose of code blocks, functions, or complex logic.
• Documentation: Document how to use functions, classes, and modules.
• Debugging: Temporarily disable code for testing or debugging purposes.
• Code Readability: Improve the overall readability and maintainability of code.
• Collaboration: Communicate with other developers working on the same codebase.

Best Practices

• Keep comments concise and relevant: Avoid writing unnecessary or redundant comments.
• Use clear and descriptive language: Make your comments easy to understand.
• Update comments when code changes: Ensure comments stay accurate and reflect the latest code logic.
• Use comments to explain “why,” not just “what”: Focus on explaining the reasoning behind your code choices.
• Don’t over-comment: Well-written code should be self-explanatory to a certain extent.
• Use docstrings for documentation: Docstrings are a standard way to document Python code and can be used to generate documentation automatically.

Example

Python

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

  Args:
    length: The length of the rectangle.
    width: The width of the rectangle.

  Returns:
    The area of the rectangle.
  """
  area = length * width  # Calculate the area
  return area

# Get the length and width from the user
length = float(input("Enter the length: "))
width = float(input("Enter the width: "))

# Calculate and print the area
area = calculate_area(length, width)
print("The area of the rectangle is:", area)

By using comments effectively, you can make your Python code more understandable, maintainable, and collaborative.