Naming best practices for robots and coding in general

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

Why is good naming important? ☝️

In the context of coding, good naming:

  • Communicates the problem the code solves. 🗺
  • Communicates the steps to solve the problem. 🚶‍♀️
  • Communicates the data needed to solve the problem. 📥
  • Makes the code self-documenting, reducing the need for comments and external documentation, mitigating the risk of comments and documentation getting out-of-sync with the code. 📚
  • Provides insight and understanding, enabling faster and more confident maintenance and modification (🏎), thus saving developer time (💰) and reducing the risk of bugs (🐞) due to misinterpretations.

What are some examples of not-so-great naming? ❌

Have you seen, or written, this kind of Python code?

def process_data(data): """Process the data. ``data`` The data. ``callback`` The callback. """ a = data.a b = data.b return process_internal(a[0], b[1])
  • What does process_data mean in practice? What kind of processing? What data?
  • What is the data argument? It could be anything!
  • The code documentation is not exactly helping: Process the data. 🤷‍♀️
  • What is the callback argument mentioned in the function docs? It's not used in the code.
  • What are the a and b variables? What do they contain?
  • What does process_internal do, and why does the code access those specific indices in a and b?
  • Why does this code provoke so many questions? I just want to do my job! 🤯

Or maybe some Robot Framework code like this:

*** Tasks *** Task 1 [Documentation] SSH into the main server and run the shell command. Click //div/div/div/div/a/span Sleep 5 seconds Click css:.row a
  • What does Task 1 mean? What are we automating here? 🤔
  • What does SSH mentioned in the documentation have to do with the browser automation code?
  • Where is the //div/div/div/div/a/span locator pointing to? What step does the clicking complete?
  • Why does the robot sleep?
  • The css:.row a selector must be important, but what link is that in practice?

Both the Python and the Robot Framework examples are concise in terms of code length and characters used. But that's about it. Fewer characters typed or lines of code written is not always a good thing.

Optimize for humans, not machines.

Computers are fast. Developers are slow. Computers and programming language interpreters are generally pretty decent at optimizing code for performance. Instead of optimizing code for the machine, you should optimize for humans! That means you and all the other developers!

Let's look at some of the pain points in the code examples above and what those pain points cause in practice.

Communicating the problem, the steps, and the data

It will take a lot of effort to understand the problem that the code solves, the steps that are taken, and the data needed. Instead of quickly proceeding with the changes you wanted to implement, you will need to spend your valuable time digging out the intent of the code, trying to understand what it does in its current form, and where to place your modifications to get to your desired end result.

Self-documenting code

The names used in the example code are too generic (process_data, data, Task 1). They have no connection to any business terms. They provide no context of the problem, or the steps, or the data.

There are some comments, but since they are "lying" (they are not in sync with the code), why should you ever trust them? They will just mislead you or raise even more questions you need to find answers to before you can do your job. In the longer term, this makes you distrust all comments, even the truly valuable ones, turning them into unnecessary clutter.

Use comments when you need to do something unconventional. Comments should provide the "why?" if something is not obvious. Unnecessary or unhelpful comments have a negative impact on development.

Insight and understanding

After reading the code, you have no idea how to proceed. Other than trying to find the original developer and asking them some serious questions. This could have been a fast thing to implement, but after seeing the code, you wave goodbye to your weekend and family.

Practical naming examples

Let's see some practical naming examples that might be a bit better than those we demonstrated with the not-so-great examples.

Tasks

*** Tasks *** Insert the new employee into the HR system

Keywords

*** Keywords *** Open the HR application

Variables

first_name = employee.first_name

Functions and Class methods

def calculate_distance(to_address, from_address):

UI locators

*** Keywords *** Open the employee details view Click alias:HRSystem.EmployeeDetailsButton Wait For Element alias:HRSystem.EmployeeDetailsView

Summary

Naming is important. Naming is also hard.

  • Use business terminology in your code. It helps in understanding the problem.
  • Use descriptive names for tasks, keywords, arguments, variables, classes, methods.
  • Aim to make your code self-documenting. Rely less on external documentation, since it might get out-of-sync.
  • Use comments when they provide value and when the code cannot communicate the "why".

Investing in good naming will pay dividends, and your fellow developers will thank you for taking the effort to make their (and your) life easier!

Resources

  • Check our Beginners' course for practical Robot Framework naming examples! Earn the Robocorp Level I certificate!
  • Read Clean Code by Robert C. Martin to learn more about creating clean code (including naming!).
  • Our Software robot project workflow course covers other best practices, such as keeping the credentials out of the code, using version control, and setting up Control Room for development and production purposes!
Last edit: June 30, 2021