Loading...
Loading...
Guidelines for self-explanatory code and meaningful documentation. Activate when working with comments, docstrings, documentation, code clarity, API documentation, JSDoc, or discussing code commenting strategies. Guides on why over what, anti-patterns, decision frameworks, and language-specific examples.
npx skill4agent add ilude/claude-code-config code-documentationcounter = 0 # Initialize counter to zero
counter += 1 # Increment counter by one
user_name = input("Enter name: ") # Get user name from inputdef 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 totaldef get_user_name(user):
return user.name
def calculate_total(items):
return sum(item.price for item in items)# 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# Start of function
def calculate():
# Declare variable
result = 0
# Return result
return result
# End of function# 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# 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# 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])# 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,}$'# 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)# 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()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)/**
* 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
}# 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
# See: docs/performance-tuning.md
CACHE_TTL = 300 # 5 minutes# TODO: Replace with proper authentication after security review
# Issue: #456
def temporary_auth(user):
return True
# WARNING: This function modifies the original array instead of creating a copy
def sort_in_place(arr):
arr.sort()
return arr
# FIXME: Memory leak in production - investigate connection pooling
# Ticket: JIRA-789
def get_connection():
return create_connection()
# PERF: Consider caching this result if called frequently in hot path
def expensive_calculation(data):
return complex_algorithm(data)
# SECURITY: Validate input to prevent SQL injection before using in query
def build_query(user_input):
sanitized = escape_sql(user_input)
return f"SELECT * FROM users WHERE name = '{sanitized}'"TODO:FIXME:HACK:NOTE:WARNING:PERF:SECURITY:BUG:REFACTOR:DEPRECATED:# Check if user is admin or has special permissions
if user.role == "admin" or (user.permissions and "special" in user.permissions):
grant_access()def user_has_admin_access(user):
return user.role == "admin" or has_special_permission(user)
def has_special_permission(user):
return user.permissions and "special" in user.permissions
if user_has_admin_access(user):
grant_access()// Good: Explains WHY we debounce
// Debounce search to reduce API calls (500ms wait after last keystroke)
const debouncedSearch = debounce(searchAPI, 500);
// Bad: Obvious
let count = 0; // Initialize count to zero
count++; // Increment count
// Good: Explains algorithm choice
// Using Set for O(1) lookup instead of Array.includes() which is O(n)
const seen = new Set(ids);# Good: Explains the algorithm choice
# Using binary search because data is sorted and we need O(log n) performance
index = bisect.bisect_left(sorted_list, target)
# Bad: Redundant
def get_total(items):
return sum(items) # Return the sum of items
# Good: Explains why we're doing this
# Extract to separate function for type checking in mypy
def validate_user(user):
if not user or not user.id:
raise ValueError("Invalid user")
return user// Good: Explains the type assertion
// TypeScript can't infer this is never null after the check
const element = document.getElementById('app') as HTMLElement;
// Bad: Obvious
const sum = a + b; // Add a and b
// Good: Explains non-obvious behavior
// spread operator creates shallow copy; use JSON for deep copy
const newConfig = { ...config };| Goal | Approach |
|---|---|
| Reduce comments | Improve naming, extract functions, simplify logic |
| Improve clarity | Use self-explanatory code structure, clear variable names |
| Document APIs | Use docstrings/JSDoc for public interfaces |
| Explain WHY | Comment only business logic, algorithms, workarounds |
| Maintain accuracy | Update comments when code changes, or remove them |