API per la spiegazione di complicati calcoli o regole aziendali?

Naviga le tue risposte
1

Nei negozi online ci sono aree con regole complicate. Ad esempio

  • è un prodotto visibile nel catalogo prodotti
  • è un prodotto esaurito
  • qual è il prezzo per il prodotto (sconti, promozioni, ...)

È una buona idea avere un'API di spiegazione aggiuntiva per ogni regola complicata?

Esempio: boolean isProductVisible() ha un String explainIsProductVisible() aggiuntivo?

Come facilitare la comprensione di queste regole?

Sfondo:

Ieri, in qualità di sviluppatore di software, ho avuto il problema che il mio prodotto di prova standard sul mio sistema di test locale era "esaurito" e avevo bisogno di questo prodotto per testare la pagina di conferma dell'ordine.

Quindi ho dovuto eseguire il debug della routine IsProductAvailable per correggere i dati di test prima di poter eseguire l'originale compito "testare la pagina di conferma dell'ordine".

Per scoprire perché il mio prodotto di test è stato esaurito, un messaggio di spiegazione sarebbe stato utile.

In una situazione simile nel motore di calcolo del prezzo ho già aggiunto messaggi di registro come questo 

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());
            }
        }
    }
    ...
}

Come sviluppatore posso esaminare il registro del server e sperare di scoprire cosa è successo.

Se fossi un product manager sarebbe più comodo avere tooltip specifici dei ruoli nella pagina web che mostra la parte della spiegazione.

Ovviamente questi tooltip non sarebbero disponibili per i clienti ordinari, solo per sviluppatori e product manager.

Le mie domande:

  • Esistono altri modi per semplificare la comprensione delle regole complicate?
  • È una buona idea avere un'API di spiegazione aggiuntiva per ogni regola complicata?
  • Una tale funzione ripaga il costo di sviluppo di questa funzione?
posta k3b 05.12.2013 - 06:33
fonte

2 risposte

1

È importante essere in grado di spiegare il risultato.

Creerei solo una funzione per questo scopo. Quando si desidera una spiegazione dettagliata del risultato, la logica per calcolare il prezzo e la logica per restituire la spiegazione sono molto simili. Come in questo pseudo codice: 

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

Vedo due implementazioni:

  1. La tua funzione restituisce un oggetto contenente il risultato e la spiegazione.
  2. La tua funzione restituisce il risultato e prende un argomento facoltativo per riferimento, che conterrà la spiegazione.

Preferirei il secondo per due motivi:

  • less refactoring del codice
  • È possibile saltare del codice nella funzione se l'argomento non è stato passato.
risposta data 05.12.2013 - 13:01
fonte
1

L'idea di restituire una spiegazione è molto buona.

Se calcoli insieme prezzo e disponibilità, puoi restituire un oggetto che descrive tutto in una volta: 

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";
}

La parte descrittiva è complicata.

Se tutto ciò di cui hai bisogno è una spiegazione per te e probabilmente l'operatore di vendita, una stringa grezza che stai creando è adeguata.

Se le tue spiegazioni sono complicate e sono presentate al cliente, avrai bisogno di un modo per formularlo piacevolmente usando tutti i dati. Creerei un Tree<String> come spiegazione, con i bambini che sono "perché" parti di un genitore. Quindi sintetizzerei una frase ben formulata guardando l'intero albero, al di fuori del metodo di calcolo del prezzo / disponibilità. Qui puoi decidere dove mettere "perché", "e", "ma", ecc, cosa mettere per primo, quale set di espressioni usare per una particolare configurazione ad albero, e così via.

    
risposta data 05.12.2013 - 07:20
fonte

Leggi altre domande sui tag

Quando scrivere la documentazione del progetto software sul codice [duplicato] Come accodare gli ordini di lavoro per data e priorità?