Master Python code commenting with our comprehensive guide. Learn best practices, conventions, and techniques for clear comments.
Python uses # for single-line comments and """...""" for multi-line comments. Following Python commenting conventions ensures your code is readable and maintainable.
Use single-line comments for brief explanations, clarifications, or notes about specific lines of code. Keep them concise and relevant to the immediate context.
// Good: Explains why, not what
// Calculate tax before shipping to comply with local regulations
const totalWithTax = subtotal * taxRate;
Use multi-line comments for longer explanations, complex algorithms, or when documenting important business logic that requires detailed context.
/*
* Complex algorithm explanation:
* 1. First step description
* 2. Second step description
*/
Use structured documentation comments for functions, classes, and modules. Include parameters, return values, and usage examples when appropriate.
/** Description of function
* @param {type} name - parameter description
* @returns {type} return value description
*/
Use standardized tags like TODO, FIXME, HACK, or NOTE to mark items that need attention. Include your initials and a date for tracking.
// TODO(username): Add error handling for edge case
// FIXME: Memory leak when processing large files
// NOTE: This approach was chosen over X because Y
Let DocuWriter.ai generate comments for your Python code automatically
Open markdown editorWant to learn more? Check out our guide on technical documentation best practices
FAQ
Add comments for complex logic, non-obvious decisions, important algorithms, and to explain the 'why' behind your code choices.
Good comments explain intent and reasoning, while bad comments state the obvious or become outdated. Focus on 'why' not 'what'.
Comments should be concise but informative. Provide enough context for others to understand without being verbose or redundant.
Related resources
Get started
Start documenting and organizing your codebase