Code Commenting Guide — Writing Comments That Help Developers

In this tutorial, you will learn about Code Commenting Guide. We cover key concepts, practical examples, and best practices to help you master this topic.

Code comments are the bridge between what code does and why it does it. Good comments make code maintainable, reviewable, and understandable. Bad comments create confusion, bugs, and Technical Debt.

In this tutorial, you will learn the different types of code comments, when to use each one, and how to write comments that help your team.

What You'll Learn

By the end of this guide, you will write docstrings, inline comments, and block comments that explain why code exists. You will know when to refactor instead of comment and how to generate documentation from comments.

Why It Matters

Code is read far more often than it is written. Comments are how you communicate with future maintainers, including your future self.

Real-World Use

The DodaTech codebase follows strict commenting standards. Every public function has a docstring. Every non-obvious decision has an inline comment explaining why.

flowchart TD
  A[Code Comments] --> B[Docstrings]
  A --> C[Inline Comments]
  A --> D[Block Comments]
  B --> E[What and How]
  C --> F[Why]
  D --> G[Design Rationale]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Common Mistakes

1. Commenting the Obvious

i += 1 # Increment i by 1 adds noise. Reserve comments for why.

2. Outdated Comments

Comments describing old behavior while code does something new. Always update comments with code.

3. No Comments on Complex Logic

Algorithmic code with no explanation of why it works that way.

4. Overcommenting

Comments on every line make code harder to read.

5. Comments Instead of Good Naming

n # number of users should be num_users.

6. No Docstrings on Public APIs

Functions without docstrings force consumers to read the implementation.

7. Commented-Out Code

Dead code left as comments. Delete it and use version control history.

Practice Questions

1. What are the three types of code comments?

Docstrings, inline comments, and block comments.

2. When should you refactor instead of comment?

When the code's purpose can be made clear through better naming and structure.

3. What is the danger of outdated comments?

They mislead future maintainers into believing old behavior is current.

4. How can you generate documentation from comments?

Using tools like Sphinx, JSDoc, Doxygen, or rustdoc.

5. Challenge: Take a file with sparse comments and rewrite all comments following best practices. Add docstrings, inline comments for non-obvious decisions, and block comments for design rationale.

FAQ

How many comments is too many?

If removing a comment does not make the code harder to understand, the comment is unnecessary.

Should I comment every function?

Every public function should have a docstring. Private helpers may not need one if their purpose is obvious.

How do I keep comments up to date?

Include comment updates in the code review checklist. Automated tools can flag TODOs.

What is a docstring?

A structured comment that documents a function, class, or module interface. It serves as the primary documentation for users of the code.

Should I use docstring generators?

Yes. Tools like Sphinx, JSDoc, and rustdoc parse docstrings and generate documentation automatically.

Mini Project

Set up a comment quality check in CI. Configure rules that enforce docstrings on public functions and flag TODOs without ticket references.

What's Next