Guidelines for using comments
Comments add information to the script. They should add relevant information.
Document complex logic with line comments
Use line comments to document blocks of code containing complex logic. You can't always prevent your solution from increasing in complexity, but you should document snippets of complex code to improve the maintainability of your script.
Include all the rationale that led you to that complex solution. Document your reasons, limitations, and what the complex logic snnipet does.
The following image illustrates this concept.
Document commands that are not obvious
Use command comments to document the purpose of the command when that purpose is not clear in the code. For example, you may need to send a keyboard entry to activate an event in an application. Document this command to state the reason for its use.
Use command comments to document the control of the graphical interface affected by the command. Some selectors may not be so evident in informing which control is the target of the command's action. Documenting which control is the target in these cases increases the maintainability of your code.
The following image illustrates this concept.
Include a header in your script
At the beginning of your script, include structured line comments to form a header with information about the script. In the header, you must insert information such as:
- Description of the script's function
- Particularities about the script's function
- Instructions for use in the case of particularities
- List of script input parameters with their respective functions
- List of script output parameters with their respective functions
The following image illustrates this concept.
Remove commented code
During testing and debugging, you can comment out code to try different solutions. At the end of these tests, remove any commented commands from your code before publishing it. The IBM RPA versioning system is sufficient to ensure that you can recover snippets of removed code, if necessary.