L12 Commenting Project

title: "Code Commenting Capstone — Apply All Commenting Principles to a Real Codebase" weight: 12 description: "Create a complete commenting standards guide and apply all commenting principles to a real codebase. Master docstrings, inline comments, block comments, action comments, and documentation generation in a comprehensive project." date: 2026-06-28 lastmod: 2026-06-28 tags: [technical-writing, code-comments]

This capstone project brings together everything you have learned about code commenting. You will create a commenting standards guide for your team, audit existing code against those standards, and improve the commenting in a real codebase.

In this project, you will produce production-ready commenting improvements.

## What You'll Learn

You will apply all commenting principles to create a commenting guide, audit code, and improve real comments.

## Why It Matters

Consistent commenting standards improve code maintainability across the team. A commenting guide ensures everyone contributes helpful comments.

## Real-World Use

DodaTech uses the commenting standards created through this process. The guide is referenced in every code review and enforced by automated tools.

```mermaid
flowchart TD
  A[Capstone Project] --> B[Commenting Guide]
  A --> C[Code Audit]
  A --> D[Comment Improvements]
  A --> E[Automation Setup]
  B --> F[Team Standards]
  C --> G[Identify Issues]
  D --> H[Fix Comments]
  E --> I[CI Enforcement]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Project Steps

Step 1: Create a Commenting Guide

Write a commenting standards guide for your team. Include rules for docstrings, inline comments, block comments, action comments, and security comments.

Step 2: Audit a Codebase

Select a module or project. Audit every comment against the guide. Categorize issues by type: missing, wrong type, outdated, what instead of why.

Step 3: Fix Comments

Rewrite all bad comments. Add missing docstrings. Remove comments that restate the obvious. Update outdated comments.

Step 4: Set Up Automation

Configure a linter to check docstring presence. Set up CI checks for TODOs without ticket references.

Step 5: Review Security Comments

Review security-critical code for comment safety. Fix any comments that reveal too much.

# Comment quality checker

def check_comment_quality(file_path: str) -> dict:
    """Check comment quality in a source file."""
    results = {
        "missing_docstrings": [],
        "obvious_comments": [],
        "todos_without_tickets": [],
        "outdated_comments": [],
    }

    with open(file_path) as f:
        lines = f.readlines()

    for i, line in enumerate(lines, 1):
        stripped = line.strip()

        # Check for obvious comments
        if stripped.startswith("#") and "import" in stripped.lower():
            results["obvious_comments"].append(i)

        # Check for TODOs without tickets
        if "TODO" in stripped and not any(
            t in stripped for t in ["FIXME-", "TODO-", "BUG-"]
        ):
            results["todos_without_tickets"].append(i)

    return results

Common Mistakes

1. No Standards

Auditing and fixing comments without a guide. Standards must come first.

2. Fixing Everything

Spending time on low-value comments. Focus on public APIs, complex code, and security-critical sections.

3. No Automation

Manual enforcement only. Automated checks catch issues consistently.

4. Ignoring Public API

Spending all effort on internal code comments while public APIs remain undocumented.

5. Not Updating the Guide

Creating the guide and never revising. Update as you discover what works.

6. No Team Buy-In

Creating commenting standards without team input. Standards nobody agrees to are ignored.

7. Not Celebrating Progress

Documentation improvements are hard to see. Track and celebrate progress.

Practice Questions

1. What is the first step in improving code comments?

Create a commenting standards guide. Without standards, there is no target to aim for.

2. What types of comments should be prioritized?

Public API docstrings, complex code inline comments, security-critical code comments.

3. How can automation help with comment quality?

Check docstring presence, flag TODOs without tickets, detect obvious comments.

4. Why is team buy-in important for commenting standards?

Standards nobody agrees to will not be followed. Involve the team in creating the guide.

5. Challenge: Complete the full capstone project for a real codebase. Create a guide, audit code, fix comments, and set up automation.

FAQ

Mini Project

Complete the full capstone: create a commenting guide, audit a module for comment issues, fix all bad comments, set up automated checking, and document the results.

What's Next