Comment

Overview

The Comment action adds documentation and notes directly within workflows. It provides inline documentation, step explanations, and context that helps team members understand workflow logic and decisions.

💬 Purpose

Use Comment to:

• Document complex logic

• Explain decision points

• Add context and reasoning

• Mark important sections

• Create readable workflows

---

When to Use Comment

✅ Good Use Cases

Scenario	Reason
Complex Logic	Explain why this decision exists
Non-Obvious Steps	Context for unusual operations
Important Sections	Mark critical workflow areas
TODO Reminders	Future work or improvements
Known Issues	Document workarounds
Important Notes	Keep team informed
Decision History	Why this approach chosen

❌ Anti-Patterns (Don't Do)

• ❌ Over-commenting obvious steps

• ❌ Letting comments get out of sync

• ❌ Using comments instead of clear step naming

• ❌ Including sensitive data in comments

• ❌ Never updating comments as workflow changes

---

Configuration

Basic Setup

1. Open your workflow

2. Click "Add Action" → Select "Comment"

3. Configure comment:

   • Type: Note, TODO, Warning, Info

   • Title (optional): Section heading

   • Content: Comment text

   • Visibility: Internal or Shared

4. Save

Configuration Options

Comment Action Configuration
├── Comment Type:
│   ├── Note: General documentation
│   ├── TODO: Action item for future
│   ├── Warning: Important caution
│   ├── Info: Informational note
│   └── Important: Critical information
├── Visibility:
│   ├── Internal: Team only
│   └── Shared: Visible to all users
├── Content:
│   ├── Title: Comment heading
│   ├── Message: Main comment text
│   └── Details: Additional context
└── Metadata:
    ├── Author: Who added comment
    └── Date: When added

---

Comment Types

Note

General documentation and explanation:

Type: Note
Title: User Login Validation
Content: 
This section validates user login credentials against
the authentication service. We use exponential backoff
retry strategy here to handle intermittent auth service
timeouts during peak hours.

Use case: Standard user authentication flow
Related: auth_service API, error handling

TODO

Reminder for future improvements:

Type: TODO
Title: Optimize Database Query
Content:
TODO: The current search query performs a full table scan.
Performance testing shows 2-second latency. Need to add
database index on user_email column to improve to <100ms.

Assigned: @dev-team
Priority: Medium
Target: Next sprint

Warning

Important cautionary information:

Type: Warning
Title: Destructive Operation
Content:
WARNING: This workflow deletes test data. Ensure this is
running in the test environment only, not production!

Verification step: Check environment variable before
execution. See line 45 for safety check.

Contact: ops-team for production concerns

Info

Informational context:

Type: Info
Title: API Rate Limit Handling
Content:
This workflow includes 3-attempt retry logic with
exponential backoff to handle API rate limiting (429
errors). Maximum wait time is capped at 60 seconds.

Rate limit: 100 requests per minute
Retry strategy: Exponential backoff (2s, 4s, 8s...)

---

Practical Examples

Example 1: Complex Decision Documentation

Workflow: Smart Report Generation

[Check data availability]
    ↓
[COMMENT: Decision Logic]
  Type: Note
  Title: Data Availability Check
  Content:
  We check data availability first because:
  1. Some days may have no data (holidays, system down)
  2. Generating empty reports wastes resources
  3. Downstream systems expect non-empty data
  
  If data available, generate report (5s)
  If not available, skip report generation (0s)
  
  This saves ~20% of processing time on average.
    ↓
[IF data_available THEN generate_report]

Example 2: TODO for Future Work

Workflow: Payment Processing

[Process payment]
    ↓
[Retry on failure]
    ↓
[COMMENT: TODO]
  Type: TODO
  Title: Implement Exponential Backoff
  Content:
  TODO: Currently using fixed 5-second retry delay.
  Replace with exponential backoff (2s, 4s, 8s) to
  reduce load on payment gateway during outages.
  
  Estimated time: 2 hours
  Priority: Medium
  Owner: @payments-team
    ↓
[Send notification on success]

Example 3: Warning for Critical Section

Workflow: Database Cleanup

[Get cleanup list]
    ↓
[COMMENT: Warning]
  Type: Warning
  Title: Production Data Protection
  Content:
  WARNING: This workflow deletes records. Always verify
  you are running in TEST environment before execution!
  
  Safety checks:
  ✅ Environment check: Line 23
  ✅ Dry-run mode option: Line 45
  ✅ Confirmation required: Line 67
  
  If running in production by mistake, STOP immediately
  and contact: [email protected]
    ↓
[IF environment == "test" THEN continue]

Example 4: Explaining Non-Obvious Logic

Workflow: Session Timeout Handling

[Wait 5 seconds]
    ↓
[COMMENT: Info]
  Type: Info
  Title: Why 5 Second Wait?
  Content:
  This 5-second wait serves multiple purposes:
  
  1. Browser Cache: CSS/JS cached after 3-5s in testing
  2. DB Replication: Data replicates in <5s normally
  3. Service Sync: Microservices sync state within 5s
  
  Shorter wait (2s): Flaky, fails 15% of time
  Longer wait (10s): Reliable but slows test by 5s
  
  5 second is optimal balance for our infrastructure.
    ↓
[Verify action completed]

Example 5: Decision History

Workflow: API Retry Strategy

[API Call]
    ↓
[Retry: 3 attempts]
    ↓
[COMMENT: Note]
  Type: Note
  Title: Why Linear Not Exponential?
  Content:
  Decision History:
  
  Previous approach (exponential backoff):
  - Max wait: 60+ seconds
  - Issue: Tests took too long
  - Decision: Too slow for daily test runs
  
  Current approach (linear backoff: 2s, 4s, 6s):
  - Max wait: 12 seconds
  - Benefit: Fast but still reliable
  - Success rate: 98% (vs 99.5% with exponential)
  - Trade-off: Acceptable for speed improvement
  
  Review Date: Q2 2024
    ↓
[Continue workflow]

---

Best Practices

✅ Do

• Document the why, not the what - Code shows what, explain why

• Keep comments current - Update when workflow changes

• Use for complex sections - Obvious steps don't need comments

• Be specific - Include examples and context

• Link to resources - Reference docs, tickets, contacts

• Use appropriate type - Warning vs Note vs Info

• Include dates - When decision was made

• Add contact info - Who to ask about this decision

• Keep concise - Multi-paragraph limits, use bullets

❌ Don't

• Over-comment - Comment obvious steps

• Duplicate information - Don't repeat what step name says

• Let comments rot - Update when logic changes

• Include sensitive data - No passwords, tokens, personal info

• Use for communication - Use chat for team discussions

• Ignore team conventions - Follow established commenting standards

• Make comments vague - "this is important" isn't helpful

• Comment every line - Only document complex decisions

• Use comments as code - Don't disable code with comments

---

Comment Templates

Template 1: Complex Decision

[COMMENT: Note]

Title: {Decision Point Name}

Content:
This workflow chooses {option A vs option B} because:

Reasons for choice:
1. {Reason 1} - {Benefit}
2. {Reason 2} - {Benefit}
3. {Reason 3} - {Benefit}

Alternative considered:
- {Alternative}: {Why rejected}

Impact: {Positive outcomes}

Related: {Links to relevant docs/tickets}

Template 2: TODO Item

[COMMENT: TODO]

Title: {What needs to be done}

Content:
TODO: {Description of work needed}

Current issue: {What's not ideal now}
Proposed solution: {How to fix}

Estimated effort: {Time to implement}
Priority: {High/Medium/Low}
Owner: @{person_responsible}
Target date: {When to complete}

Template 3: Warning

[COMMENT: Warning]

Title: {What to be careful about}

Content:
WARNING: {Specific danger or risk}

Safety checks:
✅ {Check 1} - Line XX
✅ {Check 2} - Line YY
✅ {Check 3} - Line ZZ

If something goes wrong: {Emergency procedure}
Contact: {Who to notify}

Template 4: Decision History

[COMMENT: Note]

Title: Why {current approach}?

Content:
Decision History:

Previous approach: {Old method}
- Issue: {What was wrong}
- Result: {Negative outcome}

Current approach: {New method}
- Benefit: {What improved}
- Result: {Positive outcome}

Trade-offs: {What we gave up vs gained}

Review date: {When to reconsider}

---

Organizing Comments

Section Comments

Mark major workflow sections:

[COMMENT: Note - Setup Phase]
  Content: The following steps initialize test environment
  
[Step 1: Create test data]
[Step 2: Configure endpoints]
[Step 3: Start services]

---

[COMMENT: Note - Main Test Phase]
  Content: Core workflow testing happens here
  
[Step 4: Execute test]
[Step 5: Verify results]

---

[COMMENT: Note - Cleanup Phase]
  Content: Final cleanup and reporting
  
[Step 6: Delete test data]
[Step 7: Send report]

Workflow Map

Create overview with comments:

[COMMENT: Info - Workflow Overview]
  Content:
  This workflow has 3 phases:
  
  1. SETUP (Steps 1-3): Create test environment
  2. TEST (Steps 4-8): Execute test scenarios
  3. CLEANUP (Steps 9-10): Clean and report
  
  Total runtime: ~2 minutes
  Success rate: 99%
  
  For detailed info, see each section's comment.

---

Sharing Comments

Team Guidelines

Shared (Team Visible):
- Decision explanations
- Important warnings
- Known issues and workarounds
- General documentation

Internal (Private):
- TODO items
- Personal notes
- Debugging information
- Work-in-progress notes

Documentation Extraction

Comments become part of workflow documentation:

Workflow: User Registration

Generated Documentation:
├── Overview (from comments)
├── Setup Phase (from comments)
├── Test Scenarios (from comments)
├── Expected Results (from comments)
└── Known Issues (from comments)

---

Comment Maintenance

Keeping Comments Current

When workflow changes:
1. Review affected comments
2. Update or delete outdated comments
3. Add new comments for new logic
4. Update decision dates if relevant

Quarterly review:
- Remove obsolete comments
- Update deprecated info
- Add missing context
- Review TODO items

---

Real-World Scenarios

E-Commerce Checkout Workflow

[Setup test data]

[COMMENT: Note]
  Title: Why Wait Before Checkout?
  Content:
  We wait 2 seconds after adding items because:
  - Shopping cart service: ~1s to update
  - Cache invalidation: ~1s to sync
  - Without wait: ~30% flaky failures
  
  See performance_analysis.pdf for details.

[Wait 2 seconds]
[Checkout]

API Testing Workflow

[Make API call]

[COMMENT: Warning]
  Title: Rate Limit Protection
  Content:
  WARNING: This workflow hammers the API endpoint
  Do NOT run more than 1 instance at a time
  
  Rate limit: 60 requests/minute
  Current load: 50 requests/test
  
  If exceeding, contact: [email protected]

[Retry with backoff]

Data Verification Workflow

[Query database]

[COMMENT: TODO]
  Title: Optimize Database Query
  Content:
  TODO: Current query is slow (2s latency)
  Need to add index on user_id column
  
  Effort: 30 minutes
  Priority: High (affects 10+ workflows)
  Owner: @database-team

[Wait for eventual consistency]
[Verify data]

---

Integration with Other Actions

Comment + Condition

Explain conditional logic:

[COMMENT: Note - Decision Point]
  Content: We choose path based on environment type

[IF environment == "production" THEN]
    [COMMENT: Info - Production Path]
    [Production verification steps]
ELSE
    [COMMENT: Info - Test Path]
    [Test verification steps]

Comment + Wait

Document timing decisions:

[COMMENT: Note - Timing Justification]
  Content: Wait 30s for background job to complete

[Wait: 30 seconds]

[Verify: Background job completed]

---

Related Topics

• Workflows - Workflow basics

• Action Types Overview - All actions

• Nodes and Steps - Building workflows

• Workflow Patterns - Common patterns

---

Summary

• Comment adds documentation to workflows

• Use to explain why decisions, not just what steps

• Document complex logic and non-obvious sections

• Keep comments current as workflow evolves

• Use appropriate type - Note/TODO/Warning/Info

• Include context - Examples, links, contacts

---

Next: Return to Action Types Overview to explore all available actions.