Strategic comments

Strategic Comments

Add meaningful comments that explain "why" not "what" - focusing on business logic, design decisions, non-obvious implementations, and technical debt.

When to Use This Skill

Use this skill when you need to:

• Explain complex algorithms
• Document business rules
• Clarify design decisions
• Document workarounds and technical debt
• Add context that code alone cannot convey
• Mark areas for future improvement

Trigger phrases: "add comments", "explain code", "document why", "add TODO", "clarify logic", "document workaround"

What This Skill Does

Comment Categories

1. Explanatory Comments - Why the code exists
2. Business Logic Comments - Domain rules and requirements
3. Decision Comments - Why this approach was chosen
4. Warning Comments - Gotchas and edge cases
5. Technical Debt Comments - TODO, FIXME, HACK markers

Instructions

When to Comment

Comment when code alone cannot convey:

# GOOD: Explains WHY
# Use binary search here because the list is always sorted
# by the data loader and can contain 100K+ items
index = bisect.bisect_left(sorted_items, target)

# BAD: Explains WHAT (obvious from code)
# Increment counter by 1
counter += 1

Business Logic Comments

def calculate_discount(order):
    # Business Rule: Orders over $100 get 10% discount,
    # but this doesn't stack with loyalty discounts.
    # See: JIRA-1234 for the original requirement.
    if order.total > 100 and not order.has_loyalty_discount:
        return order.total * 0.10
    return 0


def validate_transaction(transaction):
    # Regulatory Requirement (PCI-DSS 3.4):
    # Card numbers must be masked in logs and displays.
    # Only last 4 digits may be shown.
    masked = transaction.card_number[-4:].rjust(16, '*')

Design Decision Comments

# Design Decision: We use a LRU cache here instead of Redis because:
# 1. Data is request-scoped and doesn't need persistence
# 2. Latency requirements are <1ms (Redis adds 2-5ms)
# 3. Memory footprint is small (<10MB per instance)
# Revisit if we need cross-instance caching.
@lru_cache(maxsize=1000)
def get_user_preferences(user_id):
    pass


# Architecture Note: This service uses eventual consistency.
# Reads may return stale data for up to 5 seconds after writes.
# This is acceptable per product requirements (see ADR-007).
class UserProfileService:
    pass

Algorithm Comments

def find_optimal_path(graph, start, end):
    """Find shortest path using Dijkstra's algorithm.

    Algorithm choice rationale:
    - A* was considered but heuristic overhead not worth it
      for our small graphs (typically <1000 nodes)
    - Bellman-Ford not needed as we have no negative weights
    - Floyd-Warshall too expensive for single-source queries

    Time complexity: O((V + E) log V) with binary heap
    Space complexity: O(V) for distance tracking
    """
    # Priority queue ordered by distance
    # Using heapq with (distance, node) tuples
    heap = [(0, start)]

    # Track visited to avoid reprocessing
    # Important: Don't modify during iteration
    visited = set()

Warning Comments

# WARNING: This function is NOT thread-safe!
# Use with thread-local storage or external locking.
# See: https://github.com/project/issues/123
def update_global_state(new_value):
    global _state
    _state = new_value


# CAUTION: Order of operations matters here!
# Must validate before transform, as transform assumes
# valid input and will produce garbage otherwise.
def process_input(data):
    validate(data)  # Must be first
    transform(data)


# NOTE: This timeout value is tuned for production hardware.
# On dev machines, you may need to increase to 30s.
OPERATION_TIMEOUT = 10  # seconds

Technical Debt Comments

# TODO(username): Refactor to use new ConfigService
# when migration is complete (Q2 2025)
# Tracking: JIRA-5678
config = LegacyConfigLoader.load()


# FIXME: This query is O(n^2) and will be slow for large datasets.
# Need to add proper indexing or use a more efficient algorithm.
# Acceptable for MVP but must fix before launch.
def slow_search(items, criteria):
    pass


# HACK: Working around a bug in library v2.3.4
# The library doesn't handle null values correctly.
# Remove when we upgrade to v3.0+
# See: https://github.com/library/issues/999
if value is None:
    value = DEFAULT_VALUE  # Library bug workaround


# OPTIMIZE: This could be parallelized for better performance.
# Current implementation is ~500ms, target is <100ms.
# Consider using multiprocessing or asyncio.
def process_batch(items):
    pass

Module/File Level Comments

"""
User Authentication Module

This module handles all user authentication including:
- Password-based login
- OAuth2 (Google, GitHub)
- API key authentication

Security Considerations:
- All passwords are hashed with bcrypt (cost factor 12)
- Rate limiting applied to prevent brute force
- Sessions expire after 24 hours of inactivity

Dependencies:
- Requires Redis for session storage
- Requires PostgreSQL for user data

Maintainer: [email protected]
Last Security Review: 2025-01-15
"""

What NOT to Comment

# BAD: Redundant comments
# Set x to 5
x = 5

# BAD: Obvious from the code
# Loop through users
for user in users:
    pass

# BAD: Comments that will become stale
# There are 3 cases to handle
if case == 1:
    pass  # What if we add case 4?

# BAD: Commented-out code (use version control)
# old_implementation()
new_implementation()

# BAD: Venting frustration
# This stupid API doesn't work properly

Comment Style by Language

Python

# Single line comment for brief notes

"""
Multi-line block comment for longer explanations.
Use for complex algorithms or important context.
"""

JavaScript/TypeScript

// Single line comment

/*
 * Multi-line comment block
 * for longer explanations
 */

/** JSDoc for API documentation */

Java/C#

// Single line comment

/*
 * Multi-line comment block
 */

/** JavaDoc/XML doc for API documentation */

Go

// Single line comment (Go uses // for all comments)

// Multi-line comments just use
// multiple single-line comments
// This is idiomatic in Go

C/C++

// Single line comment

/*
 * Multi-line comment block
 */

/** Doxygen documentation comment */

Quality Checklist

• Complex algorithms explained
• Business logic documented
• Design decisions recorded
• Workarounds marked with tickets
• Technical debt tracked
• No redundant comments
• Comments match code
• TODO/FIXME have owners
• External references valid
• Comments reviewed with code

Common Issues and Solutions

Issue: Comments become stale

Solution: Review comments during code reviews and update alongside code changes.

Issue: Too many comments cluttering code

Solution: Prefer self-documenting code. Only comment when the "why" isn't obvious.

Issue: TODO comments never addressed

Solution: Add ticket numbers and owners. Review periodically.

Related Skills

• docstrings - Function and class documentation
• code-quality - Code quality review
• technical-documentation - Architecture documentation

---

Version: 1.0.0 Last Updated: December 2025 Based on: AI Templates documentation_generation/comments/

Iterative Refinement Strategy

This skill is optimized for an iterative approach:

1. Execute: Perform the core steps defined above.
2. Review: Critically analyze the output (coverage, quality, completeness).
3. Refine: If targets aren't met, repeat the specific implementation steps with improved context.
4. Loop: Continue until the definition of done is satisfied.