Jsdoc

Auto-activate when: User discusses comments, documentation, docstrings, code clarity, code quality, API docs, JSDoc, Python docstrings, or asks about commenting strategies. Core Principle

Write code that speaks for itself. Comment only when necessary to explain WHY, not WHAT.

Most code does not need comments. Well-written code with clear naming and structure is self-documenting.

The best comment is the one you don't need to write because the code is already obvious. The Commenting Philosophy When to Comment

✅ DO comment when explaining:

WHY something is done (business logic, design decisions)
Complex algorithms and their reasoning
Non-obvious trade-offs or constraints
Workarounds for bugs or limitations
API contracts and public interfaces
Regex patterns and what they match
Performance considerations or optimizations
Constants and magic numbers
Gotchas or surprising behaviors

❌ DON'T comment when:

The code is obvious and self-explanatory
The comment repeats the code (redundant)
Better naming would eliminate the need
The comment would become outdated quickly
It's decorative or organizational noise
It states what a standard language construct does

Comment Anti-Patterns ❌ 1. Obvious Comments

BAD:

counter = 0 # Initialize counter to zero counter += 1 # Increment counter by one user_name = input("Enter name: ") # Get user name from input

Better: No comment needed - the code is self-explanatory. ❌ 2. Redundant Comments

BAD:

def get_user_name(user): return user.name # Return the user's name

def calculate_total(items): # Loop through items and sum the prices total = 0 for item in items: total += item.price return total

Better:

def get_user_name(user): return user.name

def calculate_total(items): return sum(item.price for item in items)

❌ 3. Outdated Comments

BAD:

Calculate tax at 5% rate

tax = price * 0.08 # Actually 8%, comment is wrong

DEPRECATED: Use new_api_function() instead

def old_function(): # Still being used, comment is misleading pass

Better: Keep comments in sync with code, or remove them entirely. ❌ 4. Noise Comments

BAD:

Start of function

def calculate(): # Declare variable result = 0 # Return result return result

End of function

Better: Remove all of these comments. ❌ 5. Dead Code & Changelog Comments

BAD:

Don't comment out code - use version control

def old_function():

return "deprecated"

Don't maintain history in comments

Modified by John on 2023-01-15

Fixed bug reported by Sarah on 2023-02-03

Better: Delete the code. Git has the history. Good Comment Examples ✅ Complex Business Logic

Apply progressive tax brackets: 10% up to $10k, 20% above

This matches IRS publication 501 for 2024

def calculate_progressive_tax(income): if income <= 10000: return income * 0.10 else: return 1000 + (income - 10000) * 0.20

✅ Non-obvious Algorithms

Using Floyd-Warshall for all-pairs shortest paths

because we need distances between all nodes.

Time: O(n³), Space: O(n²)

for k in range(vertices): for i in range(vertices): for j in range(vertices): dist[i][j] = min(dist[i][j], dist[i][k] + dist[k][j])

✅ Regex Patterns

Match email format: username@domain.extension

Allows letters, numbers, dots, hyphens in username

Requires valid domain and 2+ char extension

email_pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+.[a-zA-Z]{2,}$'

✅ API Constraints or Gotchas

GitHub API rate limit: 5000 requests/hour for authenticated users

We implement exponential backoff to handle rate limiting

await rate_limiter.wait() response = await fetch(github_api_url)

✅ Workarounds for Bugs

HACK: Workaround for bug in library v2.1.0

Remove after upgrading to v2.2.0

See: https://github.com/library/issues/123

if library_version == "2.1.0": apply_workaround()

Decision Framework

Before writing a comment, ask yourself: Step 1: Is the code self-explanatory?

If YES → No comment needed
If NO → Continue to step 2

Step 2: Would a better variable/function name eliminate the need?

If YES → Refactor the code instead
If NO → Continue to step 3

Step 3: Does this explain WHY, not WHAT?

If explaining WHAT → Refactor code to be clearer
If explaining WHY → Good comment candidate

Step 4: Will this help future maintainers?

If YES → Write the comment
If NO → Skip it

Special Cases for Comments Public APIs and Docstrings Python Docstrings

def calculate_compound_interest( principal: float, rate: float, time: int, compound_frequency: int = 1 ) -> float: """ Calculate compound interest using the standard formula.

Args:
    principal: Initial amount invested
    rate: Annual interest rate as decimal (e.g., 0.05 for 5%)
    time: Time period in years
    compound_frequency: Times per year interest compounds (default: 1)

Returns:
    Final amount after compound interest

Raises:
    ValueError: If any parameter is negative

Example:
    >>> calculate_compound_interest(1000, 0.05, 10)
    1628.89
"""
if principal < 0 or rate < 0 or time < 0:
    raise ValueError("Parameters must be non-negative")

# Compound interest formula: A = P(1 + r/n)^(nt)
return principal * (1 + rate / compound_frequency) ** (compound_frequency * time)

JavaScript/TypeScript JSDoc

/**

• Fetch user data from the API.
• @param {string} userId - The unique user identifier
• @param {Object} options - Configuration options
• @param {boolean} options.includeProfile - Include profile data (default: true)
• @param {number} options.timeout - Request timeout in ms (default: 5000)
• @returns {Promise<User>} User object with requested fields
• @throws {Error} If userId is invalid or request fails
• @example
• const user = await fetchUser('123', { includeProfile: true }); */ async function fetchUser(userId, options = {}) { // Implementation }

Constants and Configuration

Based on network reliability studies (95th percentile)

MAX_RETRIES = 3

AWS Lambda timeout is 15s, leaving 5s buffer for cleanup

API_TIMEOUT = 10000 # milliseconds

Cache duration optimized for balance between freshness and load