The next step that I usually take when starting a problem definition is to create a glossary. In general, terms that are immediately recognizable by someone familiar with the domain don't need to be defined, but often a term has an ambiguous meaning or is used in a limited way in the current problem, so it will have to be explicitly defined.

One gotcha in a problem statement is inconsistency. It's essential that one word is not used to mean two different things, and that two different words are never used to mean the same thing. Your first line of defense is a glossary. Typically, you would not define problem-domain terms here. For example, you wouldn't define credit or interest if the problem domain was accounting. The current problem domain is parenting, however, so terms like credit need to be defined precisely.

The glossary is also helpful in our main goal, which is to identify the key problem-level abstractions. Often essential words and concepts that appear in the glossary don't appear in the main body of the problem statement. For example, the definition of passbook introduces the term transaction. (The notion of a transaction turned out to be significant, although I didn't come to this realization immediately.)

It's also helpful to add an Implementation Details section in the glossary to provide a place to record these details, even though they're not actually part of the problem statement per se. The sorts of things that normally would go in a Functional Requirements Specification often go into the Implementation Details.

Verify and refine the problem statement

Feeling pleased with myself for having prepared a reasonable problem statement, the next step was to do a design review. I pressed my wife, DJ, who is a programmer and domain expert -- a parent -- into service. She found various minor grammatical problems (which I must confess, I have fixed in the initial statement that you just read), but she found one serious flaw that I hadn't thought of. "You can't compute interest like that," she pointed out. "If you just divide the monthly interest by the days in the month, but compound it daily, you'll end up with a bigger balance at the end of the month than if you compute it once at the end of the month. What you need here is a nominal rate that's lower than 5% per month that will give you an effective rate of 5%." Oops. Back to the books.

In the current problem, it turns out there are two domains: parenting, of course, and to a lesser extent, finance. I had assumed that I knew enough about the latter, but clearly I was wrong. So, I dropped the design and hit the books until I understood enough about the second domain to proceed.

This problem might have emerged sooner had I not left out an essential second step to the design process: after you've become familiar with the problem domain (step 1) but before you start modeling (step 3), you must interview your users to discover what they need. I didn't think I needed to do that since I was already a domain expert -- a parent. I was wrong. Had I interviewed a second domain expert, someone not as involved as I was in the actual design (my wife for example), I probably would have gotten this interest stuff right in the first place.

Back to top

Don't step over the obvious

There are lots of other issues here, but the most important is what I call the "the bathroom effect." This name stems from an (unpublished) article that I wrote for "Dr. Dobb's Journal" a few years ago that began, "Suppose we built houses the same way we build software." (We'd all be living in a poorly built version of the Winchester Mystery House). Anyway, toward the end of the article, the buyer finally gets to see the house for the first time (after it's entirely built). Looking around with a puzzled expression, the buyer asks, "Where are the bathrooms?"

"Bathrooms?" says the contractor, "there weren't any bathrooms in the spec. It will cost a fortune to add them now; we'll have to jack-hammer up concrete,and rip open walls. Why don't we just patch on an outhouse in the back yard?"

"Waddya mean 'it wasn't in the spec'?" stammers the buyer, "Who'd be dumb enough to build a house without bathrooms?"

And that's often the problem with software. It often doesn't occur to a user to mention something he needs, precisely because it's so fundamental to the problem. It's not that the users are "hiding things from me," as many programmers say. It's that the designer doesn't know enough about the problem domain to ask the right questions.

Back to top

Don't just nod -- listen

When conducting these interviews, listen! Don't interpret. It's very important not only to capture everything that comes out in the interview (someone who can take shorthand is a real asset), but also to record the domain expert's words exactly. I've sat in many meetings where the users went on for hours without anybody writing anything down. Later on, when the user wasn't around, nobody could accurately remember what had been discussed. There's also an unfortunate tendency on the part of programmers not to pay attention to what the users say. Instead, programmers have been known to distort the user's description of what a problem is into a description of what the programmer would like the problem to be. They'll restate things, shuffle words around, translate statements out of the problem domain into a more-familiar vocabulary, and otherwise distort or modify what they hear. More often than not, what gets captured is the programmer's flawed interpretation of the problem, not the problem that the domain expert actually described.

Finally, bear in mind that most users have a long history of trying to deal with arrogant computer geeks who think that they know more about any problem than the user does. (After getting an incomprehensible set of directions, the city slicker says to the farmer, "You're not very smart, are you?" The farmer replies, "That may be so, but I'm not lost.") The problem is that many users just give up after a while. Why bother to communicate if the programmer doesn't listen? You'll have to break down these sorts of barriers.

The main issue with respect to problem statements in general is whether this level of detail belongs in it at all. Normally, the problem statement itself wouldn't go so far as to define technical terms in the actual problem domain. You'd just consult a textbook or dictionary for that purpose. Here, however, the answer is "yes" because the distinction between nominal and effective interest is not part of the actual problem domain (which is parenting). Our domain experts are parents, not bankers or accountants. We are not developing a system for use by a bank or making any attempt to model the way that a real bank works. This is a piece of kid's software, not a turn-key banking system, so we can't assume knowledge of how interest is computed on the part of our domain experts. Interest computation is an important part of defining the problem, however, so it indeed belongs in the problem statement.

It's essential to keep the problem statement focused on the problem at hand. We don't want to solve the general problem of "banking" in a piece of kid's software. On the other hand, we don't want to leave out an essential detail either. If the average reader (who is assumed to be a domain expert) needs some piece of information to make sense of the problem statement, then it belongs. If the information is an essential part of the domain, we wouldn't add it. In the current case, if I really was writing a turn-key banking system, I certainly wouldn't bother to define "effective interest" because that's something that I'd expect my domain expert to know. (By the same token, the designers must know enough about the problem domain to understand these basic terms as well. You can't design an accounting application unless you know something about accounting -- at least at the level of an intelligent layman.)

So, I dug out a finance-for-the-complete-idiot book, looked up nominal interest, and modified the definition of interest as follows:

You need to use two interest rates to solve this problem: one that the kid knows about and another that the bank uses internally.

Effective interest rate
The actual interest rate, including the effect of compounding. Given a nominal monthly rate of 5%, the effective interest rate when compounded daily is 5.12%.

Nominal interest rate
The stated interest rate, excluding the effect of compounding.

What's the effective rate, compounded daily, that would achieve a nominal monthly rate of 5%?

N = Nominal rate expressed as a decimal (.05)
P = Number of periods (30 days)
E = Effective rate expressed as a decimal
Formula:
E = (1 + N/P)P -1 = .0512

An interest rate of 5%, compounded daily, yields the same balance 
at the end of 30 days as 5.12% compounded monthly.

What nominal rate do I use if I'm compounding daily, but want an effective interest rate of 5%/month?

N = Nominal rate expressed as a decimal 
P = Number of periods (30 days)
E = Effective rate expressed as a decimal (.05)

Formula:
N = P * (E + 1)1/P -1 = .0488

An interest rate of 4.88%, compounded daily, yields the same balance 
at the end of 30 days as 5% compounded monthly.

The effective and nominal rates are the same if you compound only once in a period. That is, if you compute interest once a month, the effective and nominal monthly rates are the same.

To keep things easy to explain, the bank publishes the effective rate: "Your monthly interest rate is 10%. This means that if you keep $10 in the bank for a month, the bank will pay you a dollar."

Since interest is compounded daily, the nominal rate must be used for daily computation (so the effective rate at the end of the month comes out right). For example, given a 30-day month, and a published (effective) monthly rate of 5%, the (nominal) daily rate used in compounding is 4.88%. If you start out with $10 in the account and apply the following algorithm, you'll end up with a balance of $10.50:

  double balance = 10.00;
  int days_in_month = 30;
  double effective_rate = ->05;
  double nominal_rate = days_in_month *
                        ( Math.pow(effective_rate+1,
                                   1.0/days_in_month)
                          -1);
  for ( int i = 0; i </ days_in_month; ++i )
      balance = balance + balance *
                          (nominal_rate/days_in_month)); 

Now things are starting to look more reasonable, although it turns out that we're still not done. That's the topic of next month's column.

Resources

• Read last month's OO Design Process column, "Beginning to design software."
  
  
• Visit the Winchester Mystery House to see the results of haphazard design.
  
  

About the author

Rate this article

Comments

Back to top

Table of contents

• Verify and refine the problem statement
• Don't step over the obvious
• Don't just nod -- listen
• Resources
• About the author
• Comments