Learn Python Python Docstrings

In the previous lesson, you learned how to create single line comments and use comments to improve code readability.

In this lesson, you'll explore advanced concepts related to Python comments, including documentation strings, special comments, best practices, and common mistakes that every Python developer should know.

Note

Python does not have many different types of comments like some programming languages. However, Python developers follow several conventions for documenting code effectively.

Docstrings

A docstring (documentation string) is a special type of string used to document modules, functions, classes, and methods.

Docstrings are written using triple double quotes (""" """) or triple single quotes (''' ''').

Unlike normal comments, docstrings can be accessed while the program is running.

Output

The text inside the triple quotes describes what the function does.

Pro Tip

Use docstrings to explain the purpose of functions, classes, and modules. Use comments to explain complex logic inside the code.

Accessing a Docstring

A docstring is stored in the special __doc__ attribute.

Output

This feature is used by documentation tools and IDEs to display helpful information about functions.

Module Docstrings

A module docstring appears at the beginning of a Python file.

Output

Module docstrings describe the overall purpose of a Python file.

Function Docstrings

Every important function should have a docstring explaining what it does.

Output

Class Docstrings

Classes can also contain docstrings.

Output

Multi Line Docstrings

Docstrings can span multiple lines.

Multi line docstrings are commonly used when functions have parameters, return values, or exceptions that need explanation.

TODO Comments

Developers often leave reminders using TODO comments.

A TODO comment reminds developers that additional work needs to be completed later.

FIXME Comments

A FIXME comment indicates that a known problem exists in the code.

These comments help developers quickly identify bugs that still need attention.

NOTE Comments

A NOTE comment highlights important information.

HACK Comments

A HACK comment explains that a temporary or less than ideal solution has been used.

Developers usually replace these solutions with better implementations later.

Why Triple Quoted Strings Are Not Comments

Many beginners think triple quoted strings are multi line comments.

Actually, they are string literals.

Python ignores the string only because it is not assigned to a variable.

If it is assigned, it becomes a normal string.

Output

Caution

Triple quoted strings should not replace regular comments. Use them primarily for docstrings.

When Should You Write Comments?

You should write comments in situations like these:

Explaining complex calculations.
Describing business rules.
Documenting unusual algorithms.
Explaining important design decisions.
Recording assumptions made in the code.
Leaving reminders for future improvements.

Avoid writing comments for code that is already clear and easy to understand.

Example of Bad Comments

The comment adds no useful information because the code already explains itself.

Example of Good Comments

This comment explains why the code exists rather than describing the obvious.

Comments vs Docstrings

Feature	Comments	Docstrings
Starts With	`#`	`""" """` or `''' '''`
Executed	Ignored	Stored as documentation
Accessible Using `__doc__`	No	Yes
Purpose	Explain code	Document modules, classes, and functions
Used By Documentation Tools	No	Yes

Common Mistakes

Using Comments Instead of Clear Variable Names

Poor code

Better code

Good variable names often remove the need for unnecessary comments.

Writing Long Paragraphs as Comments

Large comment blocks can become outdated quickly.

Keep comments concise and focused.

Forgetting to Update Comments

The comment no longer matches the code and can confuse developers.

Using Triple Quotes Everywhere

Although Python allows this, the preferred approach for comments is still using the # symbol.

Stop

Never rely on outdated comments. Incorrect comments can mislead developers and introduce bugs during maintenance.

Best Practices

Write comments only when they provide useful information.
Write docstrings for every public function, class, and module.
Explain why the code exists instead of what every line does.
Keep comments short, meaningful, and up to date.
Use TODO and FIXME comments only when necessary.
Prefer descriptive variable and function names over excessive comments.
Follow a consistent commenting style throughout your project.

Great Job

You now understand advanced Python commenting techniques, including docstrings, TODO comments, FIXME comments, module documentation, function documentation, class documentation, and professional commenting practices used in real world Python projects.

Exercise

Create a function with a docstring.
Print a function's docstring using the __doc__ attribute.
Write a module docstring.
Create a class with a docstring.
Add a TODO comment to your program.
Add a FIXME comment.
Replace an unnecessary comment with a meaningful variable name.
Write a multi line docstring for a function that calculates the area of a rectangle.

Challenge

Create a Python program for a library management system.

Requirements

Add a module docstring describing the program.
Create a class with a class docstring.
Create two functions, each with its own docstring.
Add one TODO comment.
Add one FIXME comment.
Print one function's docstring using the __doc__ attribute.