Parameter Style Guide¶
It’s important to write clear names and descriptions when you define parameters in your protocols. Clarity improves the user experience for the technicians who run your protocols. They rely on your parameter names and descriptions to understand how the robot will function when running your protocol.
Adopting the advice of this guide will help make your protocols clear, consistent, and ultimately easy to use. It also aligns them with protocols in the Opentrons Protocol Library, which can help others access and replicate your science.
General Guidance¶
Parameter names are nouns. Parameters should be discrete enough that you can describe them in a single word or short noun phrase. display_name
is limited to 30 characters, and you can add more context in the description.
Don’t ask questions or put other sentence punctuation in parameter names. For example:
Dry run |
Dry run? |
Sample count |
How many samples? |
Number of samples |
Number of samples to process. |
Parameter descriptions explain actions. In one or two clauses or sentences, state when and how the parameter value is used in the protocol. Don’t merely restate the parameter name.
Punctuate descriptions as sentences, even if they aren’t complete sentences. For example:
Parameter name |
Parameter description |
---|---|
Dry run |
|
Aspirate volume |
|
Dilution factor |
|
Not every parameter requires a description! For example, in a protocol that uses only one pipette, it would be difficult to explain a parameter named “Pipette type” without repeating yourself. In a protocol that offers parameters for two different pipettes, it may be useful to summarize what steps each pipette performs.
Use sentence case for readability. Sentence case means adding a capital letter to only the first word of the name and description. This gives your parameters a professional appearance. Keep proper names capitalized as they would be elsewhere in a sentence. For example:
Number of samples |
number of samples |
Temperature Module slot |
Temperature module slot |
Dilution factor |
Dilution Factor |
Use numerals for all numbers. In a scientific context, this includes single-digit numbers. Additionally, punctuate numbers according to the needs of your protocol’s users. If you plan to share your protocol widely, consider using American English number punctuation (comma for thousands separator; period for decimal separator).
Order choices logically. Place items within the choices
attribute in the order that makes sense for your application.
Numeric choices should either ascend or descend. Consider an offset parameter with choices. Sorting according to value is easy to use in either direction, but sorting by absolute value is difficult:
-3, -2, -1, 0, 1, 2, 3 |
0, 1, -1, 2, -2, 3, -3 |
3, 2, 1, 0, -1, -2, -3 |
String choices may have an intrinsic ordering. If they don’t, fall back to alphabetical order.
Parameter name |
Parameter description |
---|---|
Liquid color |
|
Tube brand |
|
Type-Specific Guidance¶
Booleans¶
The True
value of a Boolean corresponds to the word On and the False
value corresponds to the word Off.
Avoid double negatives. These are difficult to understand and may lead to a technician making an incorrect choice. Remember that negation can be part of a word’s meaning! For example, it’s difficult to reason about what will happen when a parameter named “Deactivate module” is set to “Off”.
When in doubt, clarify in the description. If you feel like you need to add extra clarity to your Boolean choices, use the phrase “When on” or “When off” at the beginning of your description. For example, a parameter named “Dry run” could have the description “When on, skip protocol delays and return tips instead of trashing them.”
Number Choices¶
Don’t repeat text in choices. Rely on the name and description to indicate what the number refers to. It’s OK to add units to the display names of numeric choices, because the unit
attribute is ignored when you specify choices
.
Parameter name |
Parameter description |
---|---|
Number of columns |
|
Aspirate volume |
|
Use a range instead of choices when all values are acceptable. It’s faster and easier to enter a numeric value than to choose from a long list. For example, a “Number of columns” parameter that accepts any number 1 through 12 should specify a minimum
and maximum
, rather than choices
. However, if the application requires that the parameter only accepts even numbers, you need to specify choices (2, 4, 6, 8, 10, 12).
Strings¶
Avoid strings that are synonymous with “yes” and “no”. When presenting exactly two string choices, consider their meaning. Can they be rephrased in terms of “yes/no”, “true/false”, or “on/off”? If no, then a string parameter is appropriate. If yes, it’s better to use a Boolean, which appears in run setup as a toggle rather than a dropdown menu.
Blue, Red
Left-to-right, Right-to-left
Include, Exclude
Yes, No