Naming

When writing your automation scripts, focus on clear naming. Read out the tasks, keywords, variables, class methods. Do they make sense? Is it clear what the keywords are supposed to accomplish or what data the variables should hold? Are you able to follow the process flow just by reading the script?

If you find that you need to add lots of documentation regarding the purpose of your keywords, it might indicate that your keywords could have more descriptive names. Try to make your scripts as self-documenting as possible. Just like in more traditional programming, proper naming can communicate the intent without the need for additional code comments.

Use comments when you need to do something unconventional or something that might not be obvious for someone new to the system. Your script naming should communicate how the automation proceeds and what steps are involved. Your comments should provide the "why?" in case there is something that is not obvious for someone not familiar with the quirks of the system under automation.

There are only two hard things in Computer Science: cache invalidation and naming things. -- Phil Karlton