Basic Syntax
Comments and Documentation
Single-line, multi-line comments, docstrings
Interview: Code documentation
Well-documented code is a hallmark of professional Python development. Python supports single-line comments, docstrings for documentation, and type hints for static analysis.
Single-Line Comments
Use # for comments. Good comments explain why, not what. The code itself should explain what it does.
Docstrings
Docstrings are string literals that appear as the first statement in a module, class, or function. They become the __doc__ attribute and are used by help().
- Google style: Most popular, uses
Args:,Returns:,Raises:sections - NumPy style: More verbose, preferred in scientific projects
- Sphinx/reST style: Uses
:param:,:return:directives
Best Practices
- Write docstrings for all public modules, classes, and functions
- Follow PEP 257 conventions for docstrings
- Use inline comments sparingingly — only for non-obvious logic
- Keep comments up-to-date with code changes
- Use TODO and FIXME comments with issue tracker references
Use Cases
API documentation generation with Sphinx or MkDocs
IDE tooltips showing function signatures and descriptions
Onboarding new developers with self-documenting code
Doctest for automated testing of code examples in docstrings
Common Mistakes
Writing comments that restate the code instead of explaining why
Missing docstrings on public functions and classes
Not updating comments when code changes
Using triple-quoted strings as block comments instead of #