Summary

When determining the names of variables, in cases where the term "percent" is the more generally used term in relation to a concept, you should use the term "percent" rather than "ratio".  Additionally, when storing a "percent" in a float, a pattern has developed in edx-platform to store the value 1.0 to represent 100%, rather than storing 100.0.  We will continue to follow this pattern for consistency.  Lastly, you must clearly document the expected values of these variables.

Examples

• Grade Percent stored in the range [0.0, 1.0], where 1.0 represent 100%.
• Completion Percent stored in the range [0.0, 1.0], where 1.0 represent 100%.

Example Code

Here is a link to a validate_percent validator used in the Completion API.  Feel free to refactor and reuse as needed.

Frequently Asked Questions

If you are storing fractions, why not just use the term "ratio"?

There are certain domains in which the term "percent" is more commonly used and meaningful in English.  Two examples that exist in edx-platform are the phrases "grade percent" and "completion percent".  In contrast, the phrases "grade ratio" and "completion ratio" are not commonly used and understood, and thus not as quick to grasp.

If you are using the word "percent", why not store 100.0 for 100%?

For some, when storing a percent as a float it feels more intuitive to store 100% as 1.0.  Historically, grades have been stored this way inside the platform.  For consistency, we have decided to continue this practice.

Some people might be aware of this legacy pattern, or might expect the float value to be a 1.0 when representing 100%.  Others feel strongly that the term percent should use the value 100.0 to represent 100%, or would argue to instead use the term "ratio", in order to stay mathematically consistent. Any choice will lead to some people guessing correctly and other people guessing incorrectly. Therefore, it is very important to include these details in your documentation to make it explicit.