Comments / annotations best practices?

studio

#1

Hey guys,

I’ve been lurking for a while on this forum, and have my first question. We are about to use UiPath to apply RPA in our organization, and I was wondering about best practices when it comes to adding comments/annotations to the source files. These are robots that will be running for years and will need to be maintained by various people.

Quote: “Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live.” :slight_smile:

I have a programming background, and one of my main points of frustration with UiPath is readability. A robot consisting of many different .xaml files with dozens of variables and activities quickly becomes a visual mess and if you want to figure out what’s actually going on, you have to dig into the activities. If you’re not the original developer, this can be pretty rough. And even if you are, it can still be rough if you haven’t looked at it for months.

Other than obvious naming conventions, I thought about using annotations to describe the process in layman’s terms, especially with the Flow Decision and Invoke Workflow activities. I don’t like the Comment activity, because it increases visual clutter even more.

How do you guys handle this? Does anyone have any other ideas to improve readability? It doesn’t matter much for the small robots you create during your trainings, but when automating enterprise processes with dozens of variables and activities it can be quite daunting.


#2

@trog, Since you found unease with Comment activity please find below possible alternates.

  1. Add Annotations options - When you right click on an activity after you drop them in sequence/Flowchart.
  2. Apart from variable naming convention, you can rename your sequences and flowcharts (Process Specific) with names as well.

Regards,
Dominic :slight_smile:


#3

We haven’t had UiPath for long, so it’s a bit untested as far as true maintenance.

Our general plan is to explain what you’re doing & why using the annotations whenever it isn’t obvious due to the name of the activity. When in doubt, add an annotation. During the peer review process, if a question comes up why things were done a certain way, that’s another sure sign that an annotation is needed.

It’s not perfect, but it does help at least a little bit.


#4

One thing to note is that you can pin your Annotation at the top which can display the information of your sequence in a more readable format than using Comments.

I will use the Comments activity only once in a Flow chart to explain the Workflow description and detail the Arguments.

For each section of the process where I invoke a workflow as well as the States, I will pin my Annotation, and occasionally also for Decision/Switch branches. That way, you can see a general description for each task being performed in the process. I use normal annotations to describe how or why certain activities are used where not obvious, and annotate every variable and argument.

I also try to keep my important variables in a global location such as the Main and/or a configuration text/excel file. That way, I don’t need to dig for information.

So this is just my opinion, but in summary,

  • Provide a pinned annotation or Comment at the top of each workflow, describing what the module is used for and explanation of each Argument to send In and Out.
  • Use normal Annotations for every variable consistently and each activity where you want to be clear what it is doing.
  • Keep all your important variables available from the Main or config file to make that information accessible without searching for it.

I’m always looking to find new improved ways to organize and document my projects, though.

Regards.


#5

Thanks for the replies! I guess there is no real standard yet and we have to decide what works best for our own environment. I didn’t know you could pin annotations, I like the idea of describing what a workflow does at the top using a pinned annotation or a comment activity. And since annotations are visually non-intrusive, when in doubt, it’s best to add one.
Although one must take into account that the annotations need to be maintained as well.