Power Automate Standards: Commenting Code

Table of Contents
• Why Write Code Comments?
• Tips For Writing Good Comments
• Display Power Automate Expressions In The Flow Comments
• Do Not Use The Collaborative Comments Feature For Coding Comments

Why Write Code Comments?

Write comments to describe the intended goal of a section of Power Automation code. Knowing the intended goal helps identify mismatches between it and the actual code outcome. Code that has comments takes significantly less time for other developers to understand.

Tips For Writing Good Comments

Use these suggestions to write high-quality comments:

Do write comments that describe the intent of a code section. Intent means the goal.
Do not write comments that simply restate what is already made clear in the flow action’s name
Do keep comments updated when the goal of a code section changes.
Do not write so many comments they are impossible to maintain. Comments create their own technical debt.
Do write comments in full sentences and use plain language
Do not use abbreviations, acronyms or slang

Display Power Automate Expressions In The Flow Comments

Copy and paste Power Automate expressions into the comments section so they can be quickly browsed. The flow does not show the full expression without hovering on it or taking additional steps to open the code editor. Make sure to update the comments each time the expression is changed.

Do Not Use The Collaborative Comments Feature For Coding Comments

Collaborative comments are stored in a Dataverse table named Comment. They are not stored in the flow definition. When a flow is exported to another environment, its comments do not come with it. This is why collaborative comments should be used to conduct code reviews and not to comment your flows.

Questions?

If you have any questions or feedback about Power Automate Standards: Commenting Code please leave a message in the comments section below. You can post using your email address and are not required to create an account to join the discussion.