Re: [Caml-list] Style and organization of code

[Jon Harrop <jon@ffconsultancy.com>]

On Wednesday 14 March 2007 22:25, ian wrote:
> I'm looking for a guidebook or just some rules of thumb on how to organize
> my OCaml code.

An excellent question.

> Say I have a function called "solveHardProblem".   solveHardProblem relies
> on several helper functions, which are not going to be useful to any other
> functions in the program.  So, my first instinct would be to define all the
> helpers using let blocks within the definition of solveHardProblem.
>
> But that would make the definition of solveHardProblem really long --
> several screens of text -- which I've been taught to avoid.  Is it wrong to
> use a module to hide those functions if the module signature will contain
> only that of solveHardProblem?

I would recommend splitting large functions into many smaller functions. This 
has several advantages:

1. Easier to test small, self-contained units, e.g. in a top-level.

2. Environment is explicit.

3. Often more efficient.

4. Easier to assimilate bite-sized chunks of code.

5. Easier to describe/document.

6. Explicit environment makes errors in recursion easier to avoid.

> And say you DO choose to use a module...  The OCaml documentation says that
> the compiler can automatically infer the signature without the need to
> create a .mli file for it.  Does anyone actually use that feature in
> practice, or is creating a sig hard-wired to the act of creating a struct?

I often use inferred .mlis, especially during development when I need more 
flexibility. Note that you can nest modules inside compilation units as well.

In this case, if your nested module solveHardProblem would only expose a 
single value then I'd leave that function and all of its helpers inlined into 
the outer module and restrict its signature to hide the helpers.

My style has evolved significantly since I started programming in OCaml and I 
would now recommend following the style of the stdlib.

-- 
Dr Jon D Harrop, Flying Frog Consultancy Ltd.
OCaml for Scientists
http://www.ffconsultancy.com/products/ocaml_for_scientists