Logic App Best practices, Tips and Tricks: #3 Add comments

In my two previous blog posts, I talked about the most essential best practices you should have while working with Azure Logic Apps:

• #1 Logic App Naming Convention
• #2 Actions Naming Convention

Today I want to highlight another critical best practice: adding comments. This habit is common for developers, but Logic Apps reach a much broader audience. Many non‑developers work with Logic Apps, and they often aren’t familiar with standard programming practices—such as naming conventions or proper documentation. Because of that, commenting becomes even more important.

#3 Add Comments

Why is it essential to add comments to all our actions? Or at least in the most important ones?

Almost for the same reasons we describe in the previous Best Practices, Tips, and Tricks:

Improve readability

Comments help you understand the purpose of each action at a glance. Instead of opening the action and reading every setting, you can rely on a clear explanation. In many cases, the configuration alone doesn’t tell the whole story, and you still need to check external documentation. Well‑written comments save time, reduce frustration, and make the workflow easier to revisit. Even if you built the Logic App, you’ll quickly forget the details after a few weeks—or even a few days.

Share knowledge across your team

Logic Apps often involve several developers, different teams, or external consultants. Everyone needs to understand the workflow without digging into each action. Comments make that possible. They help new team members, support teams, and future maintainers understand the logic and continue the work. A good commenting strategy turns your workflow into self‑documenting code.

How can you add a comment to your action or trigger?

To add a note to an action step or trigger, you need to:

• Open your Logic App in the Azure Portal (or in Visual Studio) and click Edit.

• Then, on your action or trigger, click on the 3 dots to open the option list and then choose to Add a comment.

• A new comment section will appear on the action or trigger configuration panel, where you can enter your comment. Once the comment is entered, you can go out of the action step by moving to a new action or collapsing that action.
  • Once you leave the action, the comment will be present if you expand it again. Nevertheless, you must repeat the same process if you want to edit or delete the existing comment.

Basic rules about Action/Trigger Comments

• Logic App allows you to set a comment between a minimum of 1 and a maximum of 250 characters!
• You can now use all types of characters.
• To delete a comment, you need to edit and remove all text, basically adding an empty string.

Samples

Here are some samples and how you can use comments:

• At the Actions Naming Convention tip, I mentioned that, unfortunately, not all triggers allow you to modify the name. This is a significant limitation, in my opinion, and this behavior should be modified in the future. Still, for now, we need to deal with that limitation. One of those cases is the Request > When a HTTP request is received. So here is a good place – for me, a mandatory place – to add a good comment.
  • In this sample below, we add a comment saying: Receive a JSON with the Evaluation form OCR metadata from SmartDocumentor. Now I know that I have an HTTP trigger that is waiting for a request that is sent by a tool called SmartDocumentor, and this tool is sending a JSON with the OCR metadata of a paper form that was captured and processed.

• On Scopes. Scopes are a special kind of action that, unlike other actions, do not perform any actual work. Instead, they can contain other actions, and one of them is to act as a region where you can collapse and expand certain sections of your business workflow – but we will speak in the future about this topic.
  • Because they act as a container of several actions, here is an excellent place to add a short description and resume of the section’s main goal. For example, in the picture below, that section is responsible for containing all actions necessary to retrieve all the required parameters from KeyVault and/or the database to control and use in the rest of the business workflow

• On Conditions! A simple trick here is to put the condition syntax as a comment of the shape, and the reason is that when we use expressions, as you see in the picture below, you will only see in the design a small pink rectangle with a string(…). To understand what is there, you need to select the expression, go to the expression editor, and scroll through the small text box to read the full expression. So if you take that expression and put it in the comment, you can easily read what condition is being applied without all of this additional work.

And of course in many other places. But, again, all actions should have a comment or at least the most important ones.

Stay tuned for the following Logic Apps Best practices, Tips, and Tricks.

Hope you find this helpful! If you liked the content or found it useful and would like to support me in writing more, consider buying (or helping to buy) a Star Wars Lego set for my son.