Comment Cleanup
I'll analyze and improve the documentation in the specified file following strategic documentation principles.
Target File
$ARGUMENTS
Documentation Philosophy
Core Principles
-
Self-documenting code first - Improve naming and structure before adding comments
-
Comments capture design intent - Document WHY, not WHAT (when WHAT is obvious)
-
Reduce cognitive load - Make implicit knowledge explicit
-
Eliminate redundancy - Never restate what code already makes clear
What Makes GOOD Comments
-
Design decisions - Why this approach over alternatives
-
Non-obvious behavior - Complex logic that isn't immediately clear
-
Interface contracts - What a function/module does, parameters, returns
-
Important context - Background information needed to understand
-
Gotchas and edge cases - Subtle behaviors that could cause issues
-
Dependencies - How components relate to each other
What to AVOID
-
Redundant comments restating obvious code
-
Comments duplicating well-named variables/functions
-
Implementation details that are self-evident
-
Comments that would become outdated easily
Analysis Process
-
Read the file to understand its purpose and structure
-
Identify naming improvements that could make code more self-documenting
-
Find complex logic that needs explanation
-
Locate design decisions that should be documented
-
Remove harmful comments that add noise or are outdated
-
Add strategic comments where they reduce cognitive load
Execution
I will:
-
First read and analyze the target file
-
Suggest and apply naming improvements if needed
-
Remove redundant or misleading comments
-
Add comments only where they:
-
Explain non-obvious behavior
-
Document design decisions
-
Clarify complex algorithms
-
Provide essential interface documentation
-
Ensure all changes follow the "campsite rule" - leave code cleaner than found
The goal is minimal, high-value documentation - make code so clear it needs few comments, then add comments only where they capture essential information not expressible in code.