Skip to main content

Comments and Docstrings

Following our exploration of Basic Console Input and Output, this article focuses on how to make your code more readable and understandable using comments and docstrings.

📚 Prerequisites​

A basic understanding of Python syntax.

🎯 Article Outline: What You'll Master​

In this article, you will learn:

  • ✅ How to write comments in Python.
  • ✅ The difference between single-line and multi-line comments.
  • ✅ What docstrings are and how to write them.
  • ✅ The importance of PEP 257, the docstring convention.

🧠 Section 1: Comments​

Comments are lines in your code that are ignored by the Python interpreter. They are for humans to read and are used to explain what your code does. In Python, comments start with a hash symbol (#).

# This is a single-line comment
x = 10 # This is an inline comment

While Python doesn't have a specific syntax for multi-line comments, you can create them by using a hash symbol at the beginning of each line:

# This is a
# multi-line
# comment.

💻 Section 2: Docstrings​

A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition. Unlike comments, docstrings are accessible at runtime and are used to document your code.

Docstrings are enclosed in triple quotes (""" or ''').

def my_function():
    """This is a docstring. It explains what the function does."""
    pass

You can access the docstring of an object using the __doc__ attribute or the help() function:

print(my_function.__doc__)
help(my_function)

🛠️ Section 3: PEP 257 - The Docstring Convention​

PEP 257 is the official style guide for Python docstrings. It provides conventions for writing good, consistent docstrings.

Key Conventions:

  • One-line docstrings: For simple functions, a one-line docstring is sufficient.

    def add(a, b):
        """Return the sum of a and b."""
        return a + b

  • Multi-line docstrings: For more complex functions, a multi-line docstring should include a summary line, a blank line, and a more detailed description.

    def my_complex_function(arg1, arg2):
        """
        This is the summary line.

        This is the more detailed description of the function.
        It can span multiple lines.
        """
        pass

🔬 Section 4: Comments vs. Docstrings​

FeatureCommentsDocstrings
PurposeTo explain how your code works.To explain what your code does.
Syntax#""" or '''
AccessibilityIgnored by the interpreter.Accessible at runtime.

💡 Conclusion & Key Takeaways​

You've now learned how to make your Python code more readable and understandable using comments and docstrings.

Let's summarize the key takeaways:

  • Comments: Use # to explain your code.
  • Docstrings: Use """ to document your code.
  • PEP 257: The style guide for writing good docstrings.
  • Comments vs. Docstrings: Comments are for explaining the "how", while docstrings are for explaining the "what".

Challenge Yourself: Write a function that takes two numbers as input and returns their product. Add a docstring to the function that explains what it does.

➡️ Next Steps​

In the next article, we'll learn about "Operators: Arithmetic Operators".

Happy coding!

Glossary (Python Terms)​

  • Comment: A line of text in a program that is ignored by the interpreter.
  • Docstring: A string literal that is used to document a module, function, class, or method.
  • PEP 257: The official style guide for Python docstrings.

Further Reading (Python Resources)​