6.4 Calculation Formula Requirement Pattern

Basic Details

Related patterns:	Data type
Anticipated frequency:	Between zero and a dozen requirements, depending on the nature of the system
Pattern classifications:	Pervasive: Maybe

Applicability

Use the calculation formula requirement pattern to specify how to calculate a particular kind of value, or how to determine a value via a process of logical steps.

Do not use the calculation formula requirement pattern directly for unduly complex formulae or logic. A mathematical treatise doesn't lend itself to squeezing into a set of requirements. In such cases, write a requirement that refers to an authoritative source that defines the calculations; don't attempt to duplicate such a source. Nevertheless, the calculation formula requirement pattern may still be useful in suggesting points to mention in the requirement.

Discussion

Getting calculations correct is vital, especially when they affect the revenue of a business. The way a calculation is to be performed deserves to spelled out clearly so that everyone can see and scrutinize it. It's made more important because computers don't let us observe the act of calculating and formulae embedded in software cannot be observed by nondevelopers. It's surprising, then, that critical calculations are often not mentioned anywhere in a system's documentation, leaving the business to trust that unguided developers do the right thing. That's not good enough-and it's the requirements' responsibility to see it doesn't happen.

Write a requirement for every significant calculation the system must perform. Don't be afraid to spell out even the most obvious formula-first, because no formula is so obvious that every reader can be sure to know it, and second, because it might turn out to be not so obvious after all when you sit down to specify it properly.

Formulae for calculations need to be stated precisely, or else they risk being misinterpreted and implemented incorrectly. A calculation that's close and looks about right to the naked eye is still wrong. Expose as much as possible how the system works, and what it's doing. Let users understand, and they'll be more likely to spot when something's not working properly and they'll have more faith in the system (because it becomes less of an inscrutable monster).

For convenience, this requirement pattern uses the term "calculation" to mean a formula that yields a single result value from a number of variables and "determination" to mean a list of instructional steps to follow to yield a result value. A determination step can itself contain a calculation formula.

First get your facts straight. Don't just write what you think is common sense off the top of your head, because it may be more complicated than that. Do your homework: find a reliable source that explains your formula, if you can. It might contain an unexpected twist or two. For instance, if you think calculating simple interest for a bank account is … well … simple, you need to think again, because there are subtly different alternatives (which are spelled out in the example requirements later in this section). It's not until you discover something unexpected that you even appreciate the obvious formula might be inadequate.

Be alert to possible geographic variations (for example, again, how interest is calculated), or variations from one industry to another, or from one company to another. Don't be parochial. If you intend to support only one environment (or some other subset of all possibilities), say so explicitly. Allow variations to be accommodated via configuration where possible.

Content

A calculation formula requirement should contain these items:

Value description What is it that this formula is used to calculate?
The formula itself, in the form "«Value name» = …." Choose the name of the value carefully, because the formula constitutes a definition of this name. Make the name clear and unique within the scope of the system. Split it into more than one formula if it makes it easier to explain.
Explanations of all the variables used For each variable state all the following that are relevant:
1. Variable name. Capitalize the first letter to make it easier to distinguish in the formula. Use names consistently, especially when a value is the result of another calculation.
2. Origin. Where does the variable come from? It might be the result of another calculation formula.
3. Data type (if relevant). If a logical data type has already been defined for this value, refer to it. Otherwise, describe what kind of value it is (a whole number, a percentage, and so on) if it's not clear.
4. Allowed values or range, if relevant. For example, if the variable is a percentage, perhaps it must be in the range 0–100%.
5. Number of decimal places, if relevant.
Calculation refinements If the result must be calculated to a particular level of precision or rounded in a particular way, say so. It's usually reasonable to assume that calculations will be performed accurately, but software finds innumerable ways to trip the unwary-so if you're worried that 2 + 2 = 4.000012, explicitly insist on perfect accuracy.
Applicability limitations If this formula is suitable only in certain circumstances, say what they are (for example, for use in the United States only) so that if the system is used outside these bounds, it's clear there might be problems.
Reference Few calculation formulae used in systems are novel. Whenever possible, cite an external reference (or more than one) that explains the formula. This is important when there is a standard, law, or government or industry regulation that defines precisely must be done, especially for monetary calculations. Deviating from a prescribed way to calculate something might have unpleasant consequences.
An example If you think it makes things clearer. Or more than one.

Split a formula into more than one requirement if a single requirement would be large and unwieldy or if a subcalculation is used in more than one formula. Note that if you're using subcalculations, the variables listed in the original requirement might not be all you need, because a subcalculation might use additional variables. For example, the interest calculation formula that follows has a "number of days" variable, but the requirement specifying it uses "start date" and "end date" (among other variables).

Pay attention to the visual formatting of the formula and variables, to make them clear and easy to read. Don't try to impress your readers by making formulae look more complex than they need to be; impress them by making the complex easy to understand.

A requirement that determines a value using a sequence of logical steps is similar to a calculation requirement in its content, but it has a list of steps instead of the formula and explanations of variables. Each step is an instruction on what to do, which may itself be a formula.

Template(s)

Open table as spreadsheet

Summary	Definition
«Value name» calculation	«Value description» shall be calculated as follows: «Value name» = «Formula»
	where	«*Variable 1 name»* is «Variable 1 description»;
		*«Variable 2 name» is «Variable 2 description*»;
		…
	[«Calculation refinements».] [«Applicability limitations».] [«Reference».]
	[For example, «Example».]
«Value name» determination	«Value description » shall be determined as follows: «Step 1 description». «Step 2 description». … [«Applicability limitations».] [«Reference».]
	[For example, «Example».]

Example(s)

Open table as spreadsheet

Summary	Definition
New deposit principal calculation	The new principal of a deposit is calculated as the old principal plus the interest accrued since interest was last paid.
Simple interest calculation	Simple interest for a period of not more than one year shall be calculated as follows:
	Interest = Principal * Interest rate * Period in days / Days in year * 100
	where	Principal is the monetary amount upon which interest is earned; Interest rate is the percentage rate applicable; Period in days is the number of days' worth of interest, calculated as per the next requirement; Days in year is the number of days in the year for which the calculation is being performed, calculated as per the next requirement but one.
Interest days determination	The number of days in a period for interest calculation shall be determined as follows: Determine the calculation's month basis ("30," "30 European" or "actual") as per the next requirement but two. If the month basis is "actual," calculate and use the actual number of days between the period's start and end dates. Let D₁, M₁ and Y₁ be the day, month and year of the start date, and D₂, M₂ and Y₂ be those of the end date. If D₁ is 31, change it to 30. If the month basis is "30 European" and D₂ is 31, change the month basis to 30. If the month basis is not "30 European" and D₂ is 31 and D₁ is 30, change D₂ to 30. Calculate the number of days as: Days = (Y₂ - Y₁) * Days in year + (M₂ - M₁) * 30 + D₂ + D₁ where Days in year is determined as per the following requirement. This requirement was written with reference to http://www.investmentz.co.in/Debtz/Glossary.htm.
Interest days in year determination	The number of days in the year for which an interest calculation is to be made shall be determined as follows: Determine the calculation's year basis ("360," "365," or "actual") as per the following requirement. If the year basis is "360" or "365," use that year basis as the number of days. If the year basis is "actual" and the time period between the interest calculation start and end dates contains 29^th February, use 366 days; otherwise use 365 days.
Year basis determination	The year basis to use for an interest calculation ("360," "365," or "actual") shall be determined as follows: Use the year basis specified for the combination of banking product type and currency, if present. Use the year basis specified for the currency alone, if present. As a last resort use "360."
Month basis determination	The month basis to use for an interest calculation ("30," "30 European," or "actual") shall be determined as follows: Use the month basis specified for the combination of banking product type and currency, if present. Use the month basis specified for the currency alone, if present. As a last resort use "30."

The complexity of these interest calculation requirements-despite the formula in the first one being so straightforward-demonstrates how complexities can lurk just beneath the surface. (That's my excuse for including such long-winded examples.)

Extra Requirements

A calculation formula requirement is usually self-contained. There are, however, two kinds of extra requirements you can add if you want to do an unusually good job:

A calculation test utility A function that allows a formula to be tested in isolation-without crediting a customer with interest or charging them a fee-is useful for developers and testers. Include this utility in the production system, to let users play with it and so that the actual formula being used can be tested in production.

If a variable in a formula is calculated by another formula, insist on the ability to enter all variables explicitly. That is, enter the values that come from the original business situation, not intermediate values (though it's helpful to display what any intermediate values are). For example, for an interest calculation utility, allow the start and end dates of a time period to be entered-even though the main formula uses a number of days-but display the intermediate calculated number of days, too.
Justify each calculation The idea here is that each time a calculation formula is used, it creates a record of what it did (principally the values of the variables), so that it can be reviewed later. So few systems attempt this that it must be regarded as exotic-though it strikes me as odd that it's acceptable for such a critical aspect of systems to remain opaque and impenetrable. (Household bills, such as an electricity bill that shows "Amount charged = Unit price x Number of units," are a rare example, though even they tend to bother only when it's easy.) Perhaps tougher financial regulation of companies (such as SOX in the U.S.) might create the incentive to do this.

Considerations for Development

Develop only one implementation of each formula. Don't duplicate the code, no matter how simple the formula is. The only exception is when you need implementations in more than one programming language. For any calculation test utility you build, have it use the standard implementation of any formula it uses.

Considerations for Testing

Identify all the places where a particular calculation formula is used, and then test that in each place it is performed as promised. If you can tell that every place uses the same implementation of the formula (asking the developers is one way to find out), you need test the nitty-gritty only in one place. A calculation test utility (as just described in the "Extra Requirements" section) can be that one place; it's a convenient way to test that the formula works properly in detail. An even more convenient way is to use another utility that performs calculations using prepared test data and automatically verifies the outcomes against expected results.

Test that subcalculations (if any) or the steps in an algorithm are performed in the correct sequence.

Pick a representative set of values for each parameter in a calculation, including these: values on the limits of what's allowed (the biggest and smallest), negatives, values with different numbers of decimal places, zero. Pick another set of values that shouldn't be allowed, because they are too small or too big or for some other reason.

For each calculation you perform, work out the result you expect before the test. Otherwise you might be influenced unconsciously by the result you already have, and you might judge a slight flaw in the calculation as the way it should be done.

For each type of calculation, put yourself in a user's shoes. Does the system provide sufficient information for a user to be able to verify a calculation? Is all the information conveniently available in inquiries and reports? If not, is that acceptable? How would an auditor react if they are unable to prove the system is behaving as it should?