Question

I have functions that conceptually all return the same thing, but the result can take different forms:

function GetThingy()

There are four different functions, each can return different things:

• 0.071 (a float value representing an increase of 7.1%)
• 7.1 (a float value representing an increase of 7.1%)
• 1.071 (a float value representing an increase of 7.1%)
• "7.1%" (a string value representing a percentage of 7.1%)

What terms can I use to help document these functions return values?

I’ve come up with my own terminology:

• fraction: A fraction of one; where the value is understood to be between 0..1 (e.g. 0.07 represents 7%)
• percent: A per-one-hundred value; where the value is understood to be between 0..100 (e.g. 7 represents 7%) Note: This contrasts with a fraction, with is per-one, rather than per-hundred
• factor: A scale factor, that can be used to directly multiply; understood to be equivalent to 1+fraction (e.g. 1.07 implies an increase of 7%)
• percentage: A string that contains the actual percent character (i.e. %), suitable for display to the user, or cases that prefer the localized text (e.g. "7%" implies 7%)

So applying my own naming scheme to the functions:

• GetThingyFraction() = 0.071
• GetThingyPercent() = 7.1
• GetThingyFactor() = 1.071
• GetThingyPercentage()= "7.1%"

What say you?

Answer 1

Not really sure there is an “answer” to this, but naming the functions as you have demonstrated makes it very easy for the consumer to understand what they are getting back. I like the terms you have chosen as well.

Are you planning on implementing all four (or n) flavors of each function, or is this strictly a naming question for when different operations process the result differently?

I am not so sure about the utility of the “percentage” version. Typically making strings for UI of messages should be handled in the presentation, not in the computation. The presentation would determine how many decimal places, “%” vs. “pct” vs “percent”, etc.