Code Commenting

Code Commenting Skill

Add structured, professional comments to Python code files.

Commenting Hierarchy

Add comments in the following hierarchical structure:

1. Module-Level Docstring

Place at the top of the file using triple quotes with separator lines:

"""
============================================================================
Module Name - Brief Description
============================================================================
Detailed description of the module.

This module provides:
    - Feature 1
    - Feature 2
    - Feature 3

Note:
    Any important notes for users.
"""

2. Import Section Comments

Group imports by category using separator lines:

# =============================================================================
# Standard Library Imports
# =============================================================================
import os
import random

# =============================================================================
# Third-Party Library Imports
# =============================================================================
from tqdm import tqdm

# =============================================================================
# Project Internal Imports
# =============================================================================
from myproject.core import Module

3. Section Separators

Use fixed-length separator lines to divide code blocks:

# =============================================================================
# Type Aliases
# =============================================================================
ParamKey = Tuple[int, int]  # (num_ue, b) - parameter combination key

# =============================================================================
# Main Functions
# =============================================================================
def main():
    pass

4. Class Documentation

class Metrics:
    """
    Statistics Collector - Collect metrics during simulation.
    
    Uses Welford's online algorithm for delay statistics.
    
    Attributes:
        total_requests: Total number of requests.
        collision_failures: Number of collision failures.
    
    Note:
        Only data within the statistics window is recorded.
    """
    
    def __init__(self) -> None:
        """Initialize all statistics counters."""
        # Counters
        self.total_requests: int = 0

5. Function Documentation

Use detailed docstrings with workflow, parameters, returns, and examples:

def run_simulation(
    num_ue: int,
    frame: Frame,
) -> Dict:
    """
    Run simulation - Brief description.
    
    Detailed explanation of the function's purpose and behavior.
    
    Workflow:
        1. Step one
        2. Step two
        3. Step three
    
    Args:
        num_ue: Number of UEs.
            Detailed explanation of the parameter.
        
        frame: Frame structure configuration.
            - Sub-attribute 1
            - Sub-attribute 2
    
    Returns:
        Dict: Result dictionary.
            - key1: Description
            - key2: Description
    
    Example:
        >>> result = run_simulation(num_ue=100, frame=Frame())
        >>> print(result['success_rate'])
    
    Note:
        Any important notes.
    """

6. Step-by-Step Inline Comments

For complex functions, use step-by-step structure:

def complex_function():
    # =========================================================================
    # Stage 1: Initialization
    # =========================================================================
    
    # -------------------------------------------------------------------------
    # Step 1.1: Calculate Parameters
    # -------------------------------------------------------------------------
    # Explain why we calculate this way
    total = calculate_total()
    
    # -------------------------------------------------------------------------
    # Step 1.2: Create Instances
    # -------------------------------------------------------------------------
    instance = create_instance()
    
    # =========================================================================
    # Stage 2: Main Loop
    # =========================================================================
    
    for i in range(total):
        # ---------------------------------------------------------------------
        # Phase 1: Request Phase
        # ---------------------------------------------------------------------
        # Detailed explanation of what this phase does
        process_request()

7. Inline Comments

# Variable explanation
num_slots = 10  # m: number of request slots (paper notation)

# Condition explanation
if frame_idx < warmup_frames:
    continue  # Skip statistics during warmup period

# Algorithm step
delta = value - mean  # Welford Step 1: Calculate delta

Formatting Guidelines

Separator Lengths

• Major sections (=): 77 characters total

  # =============================================================================
  

• Minor subsections (-): 77 characters total

  # -------------------------------------------------------------------------
  

Best Practices

1. Don't repeat the code - Comments should explain "why", not "what"
2. Be consistent - Use the same commenting style throughout the project
3. Hierarchical structure - Use = for major blocks, - for sub-blocks
4. Step numbering - Use Step X.Y numbering for complex workflows
5. Type annotations - Add type explanations for important variables
6. Paper references - Note formula numbers when code implements paper equations

Workflow

1. Read the file - First read the entire file to understand its structure
2. Add module docstring - Add module-level documentation
3. Organize imports - Group imports with separator lines
4. Document classes - Add docstrings to each class
5. Document functions - Add detailed docstrings to each function
6. Add section separators - Divide code blocks with separator lines
7. Add inline comments - Add inline comments for complex logic
8. Review - Ensure comments are complete and consistent

Template Reference

For quick-reference templates, see references/templates.md.

Example: Complete File Structure

"""
============================================================================
Module Name - Brief Description
============================================================================
Module description.
"""

# =============================================================================
# Standard Library Imports
# =============================================================================
import os

# =============================================================================
# Project Imports
# =============================================================================
from project import Module

# =============================================================================
# Constants
# =============================================================================
MAX_VALUE = 100  # Maximum value limit

# =============================================================================
# Class Definitions
# =============================================================================
class MyClass:
    """Class description."""
    pass

# =============================================================================
# Main Functions
# =============================================================================
def main():
    """Main function."""
    # -------------------------------------------------------------------------
    # Step 1: Initialization
    # -------------------------------------------------------------------------
    pass

# =============================================================================
# Module Exports
# =============================================================================
__all__ = ["MyClass", "main"]