[racket] Documenting a financial model in Racket?

From: Matthias Felleisen (matthias at ccs.neu.edu)
Date: Fri Sep 9 13:49:34 EDT 2011

On Sep 9, 2011, at 11:23 AM, Grant Rettke wrote:

> Hi,
> At work I've inherited a financial application whose model that is too
> complicated to be documented.
> It has got me really curious how I might use Racket to document,
> understand, and implement the model so that we can really flesh out
> how it works. It would be useful purely from that regard, and also if
> we ever migrated to a different technology (than Java).
> What approaches, techniques, or features of Racket do you think might
> be interesting?
> My list: Typed Racket, in-code documentation, Rackunit,
> purely-functional or perhaps classes and interfaces, not sure what
> would be easier for people to read.

I like Neil's answer. Here is a supplement. 

You say 'is too complicated to be documented' but I hope that this 
is not what you mean. To be precise, I hope you mean the author didn't 
take the time to document it and that you wish to document it in a way
that you and others find useful in the future. 

In a sense you are in the same position as someone who wishes to understand
Javascript as a programming language. You can run some exploratory programs
but this approach does not produce the general insights you need to make 
predictions about the entire language. Instead you wish to (re-)engineer 
a semantic model that you can use to predict things the way weathermen
predict the weather. 

A program like yours might be as complex as a programming language but 
I am sure it needs a slightly different approach. 

If the program has a test suite, I would try to use the test suite 
to develop a mathematical understanding of this model: 

  a concise, short, executable specification. 

I insist on executable so that you can run it on the existing test
suite. As you recover the underlying mathematical model in this manner
you get (1) useful documentation and (2) a second but possibly slow 
implementation. I claim that Racket and or Typed Racket are one good 
way to develop this executable model. When you have covered the entire
test suite, you can start working on the [Typed]Racket with the methods
that Neil proposed. 

If your program does not have a test suite, your first job to understand
and document it is to create a test suite. 

-- Matthias

Posted on the users mailing list.