Explore how clear 'what' comments in automation improve clarity and efficiency. Discover AI Naanji's methods for better documentation today.image

Why Comments Should Explain ‘What’ for Better Automation

Maybe Comments _Should_ Explain ‘What’: Why Smart Documentation Matters for Digital Teams in 2024

Estimated reading time: 5 minutes

  • Comments should explain ‘what’ code or workflows are doing, not just ‘why.’
  • Clear documentation benefits business teams using automation platforms like n8n.
  • Understanding your code simplifies debugging, scaling, and onboarding.
  • Thoughtful documentation aids AI assistants in better workflow interpretation.
  • Use the *Maybe Comments _Should_ Explain ‘What’* principle to future-proof operations.

Table of Contents:

Why *Maybe Comments _Should_ Explain ‘What’* Is Relevant to Modern Business Automation

Commenting in code or documentation has always involved trade-offs: too much detail and it becomes cluttered, too little and you leave future developers—or your AI systems—in the dark. The original essay on “What” comments crystallizes a growing realization: the *what* matters as much, if not more than, the *why*, particularly in collaborative or scalable environments.

In digital businesses leveraging tools like n8n, Zapier, or Make.com, this approach becomes even more valuable. These platforms often use low-code visual interfaces where workflows represent business logic but not always intuitive logic. A workflow might generate invoices, trigger Slack notifications, and query an API—but without clear comments describing *what* each step does, a teammate (or AI tool) can’t easily step in to troubleshoot or optimize.

Use Case: A marketing team sets up an automated sequence in n8n that enriches CRM data and launches retargeting ads. If the team only documents *why* they want to reach lapsed customers, but not *what* each module in the flow is doing (e.g., “merge duplicates using email hash”), later editing becomes risky and inefficient.

What Are the Top Benefits of the *Maybe Comments _Should_ Explain ‘What’* Approach?

Here are five key advantages that show why this mindset is critical for teams digitizing their operations:

  1. Enhanced Onboarding for Non-Developers: When business users—like marketers or sales ops—start using platforms like n8n, clarity in workflow annotation is vital. These users are not usually trained developers, so they depend on explicit “what” instructions to understand how each part of the system functions.
  2. AI-Powered Assistants Require Descriptive Logic: AI systems that help generate or debug code rely on surrounding context. Documenting *what* is happening at each step improves prompt quality and response accuracy from AI agents like GitHub Copilot or ChatGPT.
  3. Debugging Becomes Faster and Safer: Without good documentation, even small changes to an existing system can cause cascading issues. Clear “what” comments help identify where bugs originate or what the original logic expected.
  4. Interoperability Across Tools and Roles: Businesses rely on interconnected apps: CRMs feed into analytics dashboards, which then power automated reports. A small change in one service can ripple across the entire stack. With proper “what” documentation, teams can audit automations more easily and build resilience.
  5. Compliance and Customer Privacy: Data handling workflows often involve sensitive information. Accurately recording *what* is happening to customer data adds a layer of compliance-friendly transparency internally and externally.

How Does This Apply to Low-Code Platforms Like n8n?

For businesses using low-code or no-code platforms, proper annotation may feel like overkill—especially on platforms like n8n where workflows are visual by design. However, this is where *Maybe Comments _Should_ Explain ‘What’* becomes uniquely powerful.

Because users often re-enter flows weeks or months after building them, it’s easy to forget what a specific node does—especially when the logic involves API calls or dynamic expressions. A “Send HTTP Request” block might seem self-explanatory on day one, but without details, it’s unclear what data it’s sending or which system it’s querying weeks later.

Use Case Example: A solopreneur uses n8n to sync inventory between Shopify and a third-party logistics partner. One node parses webhook data. Labeling it with a “why” comment (“we need logistics to know when stock changes”) isn’t enough. A “what” comment (“parsing POST data for SKU and inventory values”) offers concrete value during edits or audits.

Pros of Well-Annotated Workflows:

  • Easier AI-driven augmentation or debugging
  • Faster team onboarding and handoff
  • Lower risk of breaking production automations

Cons:

  • Takes extra time upfront to annotate well
  • Requires shared commenting standards among collaborators

How to Implement This in Your Business

Thinking of building or revising your automated systems? Here’s how to adopt the *Maybe Comments _Should_ Explain ‘What’* mindset across your workflows:

  1. Audit Existing Documentation:
    • Review AI scripts, Zapier/n8n flows, and internal process docs.
    • Note where approaches explain *why* decisions are made but skip *what* is being done.
  2. Create Commenting Guidelines:
    • Standardize on a “what + why” format for internal teams.
    • Example: // Filter contacts with no email (what) since email is key to campaign (why)
  3. Use Native Annotation Tools:
    • Leverage built-in commenting features in platforms like n8n, GitHub, or Notion to embed documentation right inside workflows.
  4. Automate the Review Process:
    • Integrate linting or AI code review tools that flag undocumented or unclear workflow blocks.
  5. Train Teams and Clients:
    • Provide quick training or refreshers on writing effective ‘what’ comments during onboarding or workflow handoffs.
  6. Monitor and Iterate:
    • As workflows evolve, update comments to reflect the current reality—not just the original intention.

How AI Naanji Helps Businesses Leverage This Principle

At AI Naanji, we help businesses not just automate—but automate intelligently. As part of our n8n workflow development and AI consulting services, we embed clear “what + why” documentation directly into each solution we deliver.

By emphasizing transparency and comprehension, we ensure your systems remain intuitive to both users and AI. Whether it’s integrating with CRMs, building intelligent marketing funnels, or deploying Slack bots, AI Naanji prioritizes maintainable, explainable automation.

We also offer audits that flag unclear logic or underdocumented components in your existing workflows, helping future-proof your digital operations.

FAQ: Maybe Comments _Should_ Explain ‘What’

  • Q1: Why not just comment on the “why” behind code? Isn’t that more insightful?
    The “why” is important, but without understanding the “what,” reviewers or AI tools may misinterpret what the workflow or code is actually doing—especially during maintenance or debugging.
  • Q2: How do “what” comments help with automation tools like n8n?
    Many n8n nodes perform complex operations but look generic (like HTTP requests). “What” comments clarify their role and reduce guesswork for collaborators or when scaling the system.
  • Q3: What’s a simple structure for effective comments?
    A quick formula: What is happening + Why it matters. For example:
    // Extract email addresses from contact form submissions (what) to build the newsletter list (why)
  • Q4: Does this slow down development time?
    A little bit at first—but it speeds up future debugging and team onboarding significantly. It’s an investment in technical debt reduction.
  • Q5: Can AI tools write ‘what’ comments for me?
    Yes—and better when the code is structured clearly. Tools like GitHub Copilot or ChatGPT perform better when the existing context includes clear operations and identifiers.

Conclusion

In our increasingly automated world, clarity isn’t optional—it’s foundational. The idea that *Maybe Comments _Should_ Explain ‘What’* challenges outdated norms in code documentation and pushes us toward better collaboration and smarter AI workflows. For businesses leveraging platforms like n8n and aiming to scale efficiently, embedding this philosophy into your operational DNA can reduce errors, improve onboarding, and unlock scalable growth.

If you’re ready to simplify and future-proof your automation with thoughtful design and clear documentation, reach out to AI Naanji to explore custom solutions tailored to your digital landscape.

Related Posts