integrate-comments-into-development-workflow

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:

1. Design the logic in pseudocode first
2. Convert the pseudocode into comments
3. Implement the actual code based on the comments

3. Address Design Complexity

If the design is too complex to code or comment:

1. Simplify the design first
2. Don't worry about comments or code until the design is clear
3. 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.