API for expanation of complicated calculation or business rules?

Question

In online shops there are areas with complicated rules. For example

is a product visible in the product catalog
is a product sold out
what is the price for the product (Discounts, Promotions, ...)

Is it a good idea to have an additional explanation API for each complicated rule?

Example: boolean isProductVisible() has an additional String explainIsProductVisible()?

How to make understanding these rules easier?

Background:

Yesterday I as a software developer had the problem that my standard-testproduct on my local test system was "sold out" and I needed this product to test the order-confirmation page.

So I had to debug the IsProductAvailable routine to correct the test data before I was able to do the original task "test the order-confirmation page".

In order to find out, why my test product was sold out an explanation message would have been helpful.

In a similar situation in the price calculation engine I already added log messages like this

double calculateItemPriceForProduct(Product product, int quantity, Cart cart, ...)
{
    double cumulatedPrice = 0;
    ...
    if (quantity > 1) {
        Price price = getScalePrice(product, quantity);
        if (price != null) {
            cumulatedPrice = price.getValue();
            if (log.isDebugEnabled()) {
                log.debug("calculateItemPriceForProduct("+
                    product.getCode()+
                    ") using scalePrice " + 
                    price.getCode() + " for quantity " + 
                    quantity + ":" + price.getValue());
            }
        }
    }
    ...
}

As a developer I can look into the server log and hopefully find out what happened.

If I were a product manager it would be more comfortable to have role-specific tooltips on the webpage that shows the explanation part.

Of course these tooltips would not be available for ordinary customers, just for developers and product managers.

My questions:

Are there other ways to make understanding complicated rules easier?
Is it a good idea to have an additional explanation API for each complicated rule?
Does such a feature pay off the cost of developing this feature?

side note `calculateItemPriceForProduct` code seem to have couple [WTFs](http://programmers.stackexchange.com/a/126495/31260), in particular ["arrowhead" anti-pattern](http://programmers.stackexchange.com/a/206842/31260) and unjustified use of [logging guards](http://commons.apache.org/proper/commons-logging/guide.html#Code_Guards) — gnat, Dec 05 '13 at 12:15

score 1 · Answer 1 · answered Dec 05 '13 at 06:20

The idea to return an explanation is very good.

If you calculate price and availability together, you could return an object describing all at once:

enum StockAmount {
  NONE, // unavailable
  LITTLE, // will not last
  ENOUGH, // some safe amount
  PLENTY  // the store is full
}

interface ProductAvailability {
  int getPrice(); // money is never a float! I'd store price * 100.
  StockAmount getAmount();
  int getDiscount(); // again, in cents
  String getExplanation(); 
}

// usage, crudely

ProductAvailability prod = store.getProductAvailability(product_id,...);
if (prod.getAmount() == NONE) { 
  return "Sold out!";
} else if (prod.getAmount() == LITTLE) {
  return "Take while it lasts! Only " + formatMoney(prod.getPrice()) + "!";
} else {
  return "In stock";
}

The description part is tricky.

If all you need is some explanation to you and probably the sales operator, a crude string you currently create is adequate.

If your explanations are complicated and are presented to the customer, you'll need a way to nicely formulate it using all the data. I'd build a Tree<String> as the explanation, with children being 'because' parts of a parent. Then I'd synthesize a nicely-worded sentence looking at the entire tree, outside the price/availability calculation method. Here you can decide where to put 'because', 'and', 'but', etc, what to put first, what set expression to use for a particular tree configuration, and so on.

score 1 · Accepted Answer · answered Dec 05 '13 at 12:01

It is important to be able to explain the result.

I would create only one function for this purpose. When you want a detailed explanation of the result, the logic to calculate the price and the logic to return the explanation are very similar. Like in this pseudo code :

if(product is discounted){
    price = 2
    explain = 'product is discounted'
} else price = 10

I see two implementations :

Your function returns an object containing the result and the explanation.
Your function returns the result and takes an optional argument by reference, which will contain the explanation.

I'd prefer the second for two reasons :

less code refactoring
You could skip some code in the function if the argument was not passed.

API for expanation of complicated calculation or business rules?

2 Answers2