| name | integrate-comments-into-development-workflow |
| description | A workflow for writing code comments concurrently with development to ensure accuracy and reduce rework. Use when actively coding, planning development tasks, or addressing code maintainability in ongoing software projects. |
Integrate Comments into Development Workflow
When to Use This Skill
- When actively writing code for a software project
- When planning development tasks and estimating time
- When concerned about code maintainability and documentation
- When experiencing resistance to writing comments during development
Core Procedure
1. Write Comments Concurrently
- Write comments as you code, not after
- Treat commenting as part of the coding process, not a separate task
- Never defer commenting to the end of the project
2. Handle Intense Focus Scenarios
If writing comments during coding interrupts your flow:
- Design the logic in pseudocode first
- Convert the pseudocode into comments
- Implement the actual code based on the comments
3. Address Design Complexity
If the design is too complex to code or comment:
- Simplify the design first
- Don't worry about comments or code until the design is clear
- Once simplified, proceed with concurrent commenting
Why This Matters
Leaving comments to the end creates problems:
- Increased effort: Becomes a large, separate task that feels overwhelming
- Time waste: Requires recalling or re-understanding code logic instead of documenting current thoughts
- Inaccuracy: Assumptions and design nuances are forgotten, leading to misleading comments
Expected Outcome
Comments written concurrently with code, ensuring accuracy and reducing future rework.
