Comments & Docstrings in Python
Comments and docstrings are used in Python to explain code and make programs easier to understand. Writing clear documentation inside the code helps other developers, as well as your future self, understand what a program is doing.
Comments are ignored by the Python interpreter during execution, while docstrings are used to document modules, functions, classes, and methods.
What are Comments in Python?
A comment is a line of text that explains the code. Comments are not executed by Python and are only used to improve code readability.
In Python, comments start with the # symbol.
The interpreter ignores the comment and only executes the print statement.
Single-Line Comments
Single-line comments are commonly used to explain a specific line of code.
These comments help programmers understand the purpose of each line.
Inline Comments
Inline comments are written on the same line as the code.
Inline comments should be used carefully so they do not reduce readability.
Multi-Line Comments
Python does not have a dedicated syntax for multi-line comments, but multiple single-line comments can be used together.
Another common method is to use triple quotes, which are technically multi-line strings but often used as comments.
What are Docstrings?
Docstrings (documentation strings) are special strings used to document Python modules, functions, classes, and methods. They are written using triple quotes (''' or """).
Docstrings are different from comments because they are stored as part of the object and can be accessed using Python's built-in documentation tools.
Function Docstring Example
The text inside triple quotes describes what the function does.
Accessing Docstrings
You can access a docstring using the __doc__ attribute.
This prints the documentation of the function.
Docstrings for Classes
Docstrings can also describe classes and their behavior.
This docstring explains the purpose of the class.
Types of Docstrings
- Module Docstrings – Describe the purpose of an entire module.
- Function Docstrings – Explain what a function does.
- Class Docstrings – Document classes and their attributes.
- Method Docstrings – Explain methods inside a class.
Best Practices for Writing Comments and Docstrings
- Write comments only when necessary.
- Keep comments clear and concise.
- Use docstrings to document functions and classes.
- Follow Python documentation conventions such as PEP 257.
- Avoid redundant comments that simply repeat the code.
Real-World Example
This docstring clearly explains the purpose of the function and its parameters.
Conclusion
Comments and docstrings are important for writing clean, maintainable Python code. Comments help explain specific lines of code, while docstrings provide detailed documentation for functions, classes, and modules.
Using proper documentation makes code easier to understand, debug, and maintain, especially when working in teams or building large applications.
In the next tutorial, we will explore Functions in Python and learn how to create reusable blocks of code.
