Style and organization of code

Style and organization of code

[ian]

I'm looking for a guidebook or just some rules of thumb on how to organize my
OCaml code.

One example:

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?

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?

Thanks,
-Ian

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

[ian]

Tom wrote:
> OCaml functions, values, types,
> and exceptions are usually not named lowerUpperCase, but
> words_with_underscores - it is somewhat disfunctional for us coming from
> "other" parts of the world (typing _ includes pressing the Shift key)
> but so is typing uppercase letter - there are no other alternatives.
> Anyways, better stick to the convention.

OK.  I was getting the lowerUpperCase from "Naming and Declarations" in this
document:
http://www.cs.caltech.edu/~cs20/a/style.html

Is that out of date?  If so, can you point me to a newer/better one?
Alternatively, how would you fill in that table?

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

[Tom]

[-- Attachment #1: Type: text/plain, Size: 1898 bytes --]

On 14/03/07, ian <fist_187@softhome.net> wrote:
>
> I'm looking for a guidebook or just some rules of thumb on how to organize
> my
> OCaml code.
>
> One example:
>
> Say I have a function called "solveHardProblem".


So, this is the first place for change. OCaml functions, values, types, and
exceptions are usually not named lowerUpperCase, but words_with_underscores
- it is somewhat disfunctional for us coming from "other" parts of the world
(typing _ includes pressing the Shift key) but so is typing uppercase letter
- there are no other alternatives. Anyways, better stick to the convention.

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?


No.

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?


Hm... well... I mean, the compiler can actually infer things for you, but
this simply means that you don't NEED to include a signature - it's not a
compile time error if you omit it. But the comiler will assume that you want
all the values (including functions) and types from this module to be
exported. So .mli signatures are actually used for limiting exports. Exactly
what you're trying to do.

Or you can simply define helper functions, and never use them.

- Tom

[-- Attachment #2: Type: text/html, Size: 2619 bytes --]

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

[Chris King]

On 3/14/07, ian <fist_187@softhome.net> wrote:
> 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.

I usually do exactly that.  I think it's fine to have a long let like
this, so long as it's made up of small, manageable pieces.  The
biggest problem is that your arguments are now miles away from the
definition of your function, but this can be solved with something
like the following:

let solve_hard_problem =
    let solve_simpler_problem x = ...
    and solve_something_else x = ... in
    fun x y z ->
        [code goes here]

This is also a good trick for moving a global variable (such as a
unique ID counter or a hash table) into the scope of the function that
uses it.

FWIW I've seen some examples of this style in the standard library.
genlex.ml has a 150+ line function of the form:

let make_lexer keywords =
  let kwd_table = Hashtbl.create 17 in
  List.iter (fun s -> Hashtbl.add kwd_table s (Kwd s)) keywords;
  let ident_or_keyword id = ...
  and keyword_or_error c = ...
  [snip]
  in
  fun input -> Stream.from (fun count -> next_token input)

Since the "keywords" argument is needed by the helper functions, it
appears at the top in the let, but "input" isn't and so it was moved
to the bottom in the fun.  None of the helper functions are much
longer than one screenful so it makes for easy reading.

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

[Chris King]

On 3/14/07, Chris King <colanderman@gmail.com> wrote:
> Since the "keywords" argument is needed by the helper functions, it
> appears at the top in the let, but "input" isn't and so it was moved
> to the bottom in the fun.

Oops, on second thought, this was much more likely done to reduce
overhead when the function returned by "make_lexer keywords" is used
multiple times (which it likely will be).  But even if it weren't,
that's still the style I'd recommend :)

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

[skaller]

On Wed, 2007-03-14 at 17:25 -0500, ian wrote:
> I'm looking for a guidebook or just some rules of thumb on how to organize my
> OCaml code.

> But that would make the definition of solveHardProblem really long -- several
> screens of text -- which I've been taught to avoid.  

Yeah, this is a problem with functional programming .. i have
functions that are hundreds of lines long.

Generally you want to factor out functions with minimal coupling
to the enclosing function's environment, and leave them in
if they're heavily coupled.

Furthermore if that helper is reasonably general OR it has
some semantics which are separately understandable .. you can
put that function in a separate file for additional decoupling.

> Is it wrong to use a module
> to hide those functions if the module signature will contain only that of
> solveHardProblem?

That's the normal thing to do.

Furthermore if that helper is reasonably general OR it has
some semantics which are separately understandable .. you can
put that function in a separate file for additional decoupling.

This has the downside that Ocaml's namespace management is weak,
so your function is now fully public.

But smaller modules are more pleasing and easier to manage,
so it is probably worth while.

In particular if you use 'open Module' a lot, then the
dependencies both ON and OF that module are more refined
and explicit. This is also a reasonable first order approximation
to measuring the 'coupling' between components.

> 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 personally never do this: there is always an mli file for 
every ml file -- even if the build script makes it by copying
the mli file.

-- 
John Skaller <skaller at users dot sf dot net>
Felix, successor to C++: http://felix.sf.net

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

[Gabriel Kerneis]

[-- Attachment #1: Type: text/plain, Size: 463 bytes --]

Le Wed, 14 Mar 2007 20:03:32 -0500, ian <fist_187@softhome.net> a
écrit :
> OK.  I was getting the lowerUpperCase from "Naming and Declarations"
> in this document:
> http://www.cs.caltech.edu/~cs20/a/style.html
> Is that out of date?  If so, can you point me to a newer/better one?
> Alternatively, how would you fill in that table?

If you can read french : 
http://caml.inria.fr/pub/old_caml_site/FAQ/pgl-fra.html

Regards,
-- 
Gabriel Kerneis


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

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

[Maxence Guesdon]

On Thu, 15 Mar 2007 09:02:41 +0100
Gabriel Kerneis <gabriel.kerneis@enst.fr> wrote:

> Le Wed, 14 Mar 2007 20:03:32 -0500, ian <fist_187@softhome.net> a
> écrit :
> > OK.  I was getting the lowerUpperCase from "Naming and Declarations"
> > in this document:
> > http://www.cs.caltech.edu/~cs20/a/style.html
> > Is that out of date?  If so, can you point me to a newer/better one?
> > Alternatively, how would you fill in that table?
> 
> If you can read french : 
> http://caml.inria.fr/pub/old_caml_site/FAQ/pgl-fra.html

This page and its english version were ported to the new site some
months ago:
  http://caml.inria.fr/resources/doc/guides/guidelines.fr.html
  http://caml.inria.fr/resources/doc/guides/guidelines.en.html

Regards,

-- 
Maxence Guesdon
http://yquem.inria.fr/~guesdon/
http://devel.inria.fr/rocq/

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

[Gabriel Kerneis]

[-- Attachment #1: Type: text/plain, Size: 445 bytes --]

Le Thu, 15 Mar 2007 09:09:17 +0100, Maxence Guesdon
<maxence.guesdon@inria.fr> a écrit :
> This page and its english version were ported to the new site some
> months ago:
>   http://caml.inria.fr/resources/doc/guides/guidelines.fr.html
>   http://caml.inria.fr/resources/doc/guides/guidelines.en.html

Thanks a lot, I couldn't find it.
Now, what about translating it to the "revised" syntax ? ;-)

Sincerely,
-- 
Gabriel Kerneis


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

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

[micha]

Am Thu, 15 Mar 2007 15:01:12 +1100
schrieb skaller <skaller@users.sourceforge.net>:

> On Wed, 2007-03-14 at 17:25 -0500, ian wrote:
> > I'm looking for a guidebook or just some rules of thumb on how to
> > organize my OCaml code.
> 
> > But that would make the definition of solveHardProblem really long
> > -- several screens of text -- which I've been taught to avoid.  
> 
> Yeah, this is a problem with functional programming .. i have
> functions that are hundreds of lines long.
> 
> Generally you want to factor out functions with minimal coupling
> to the enclosing function's environment, and leave them in
> if they're heavily coupled.
> 
> Furthermore if that helper is reasonably general OR it has
> some semantics which are separately understandable .. you can
> put that function in a separate file for additional decoupling.
> 
> > Is it wrong to use a module
> > to hide those functions if the module signature will contain only
> > that of solveHardProblem?
> 
> That's the normal thing to do.
> 
> Furthermore if that helper is reasonably general OR it has
> some semantics which are separately understandable .. you can
> put that function in a separate file for additional decoupling.
> 
> This has the downside that Ocaml's namespace management is weak,
> so your function is now fully public.
> 
> But smaller modules are more pleasing and easier to manage,
> so it is probably worth while.
> 
> In particular if you use 'open Module' a lot, then the
> dependencies both ON and OF that module are more refined
> and explicit. This is also a reasonable first order approximation
> to measuring the 'coupling' between components.
> 
> > 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 personally never do this: there is always an mli file for 
> every ml file -- even if the build script makes it by copying
> the mli file.
> 

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

[ian]

Gabriel Kerneis wrote:
> Le Thu, 15 Mar 2007 09:09:17 +0100, Maxence Guesdon
> <maxence.guesdon@inria.fr> a écrit :
>> This page and its english version were ported to the new site some
>> months ago:
>>   http://caml.inria.fr/resources/doc/guides/guidelines.fr.html
>>   http://caml.inria.fr/resources/doc/guides/guidelines.en.html

Merci!  C'est exactament ce que je cherche!

-Ian

dynamically finding libraries

[Vu Ngoc San]

I have a program compiled to native code on a linux machine, which uses 
some more-or-less "standard" library like libpangocairo-1.0.so.0.
Since this library is not universally present on all linux boxes, I 
suspect it might be not so easy for an average user to install it. 
Moreover, it's very small. Therefore I decide to ship it with my software.

The question is: is there a way to decide, at run-time, whether the user 
already has this library or not ? If so, I can ignore (and even delete) 
the version I shipped, and use the user's library. If not, I fall back 
on "my" version.


San

Re: [Caml-list] dynamically finding libraries

[Eric Cooper]

On Thu, Mar 15, 2007 at 02:38:25PM +0100, Vu Ngoc San wrote:
> The question is: is there a way to decide, at run-time, whether the user 
> already has this library or not ?

if pkg-config --exists pangocairo; then
    echo yes
else
    echo no
fi


-- 
Eric Cooper             e c c @ c m u . e d u

slightly OT: anyone reading this list with Mutt?

[Eric Cooper]

When I list-reply to a message on this list, my outgoing message
header gets set to
    caml-list@yquem.inria.fr, caml-list@inria.fr

When I notice it, I can manually delete one, but I often forget,
resulting in a duplicated post.  Does this happen to anyone else, and
is there a fix?

-- 
Eric Cooper             e c c @ c m u . e d u

Re: [Caml-list] slightly OT: anyone reading this list with Mutt?

[Stefano Zacchiroli]

On Thu, Mar 15, 2007 at 01:29:22PM -0400, Eric Cooper wrote:
> When I list-reply to a message on this list, my outgoing message
> header gets set to
>     caml-list@yquem.inria.fr, caml-list@inria.fr
> 
> When I notice it, I can manually delete one, but I often forget,
> resulting in a duplicated post.  Does this happen to anyone else, and
> is there a fix?

It does happen to me as well. I've no solution, but I can bet a reason:
the caml list set both Mail-Followup-To and List-Post headers. The
former is (correctly) set to caml-list@inria.fr, while the latter is set
to caml-list@yquem.inria.fr.

Either removing the List-Post header or setting it to caml-list@inria.fr
email address solves the problem.  Unfortunately I've no ready
workaround for the current state of affairs.

Cheers.

-- 
Stefano Zacchiroli -*- Computer Science PhD student @ Uny Bologna, Italy
zack@{cs.unibo.it,debian.org,bononia.it} -%- http://www.bononia.it/zack/
(15:56:48)  Zack: e la demo dema ?    /\    All one has to do is hit the
(15:57:15)  Bac: no, la demo scema    \/    right keys at the right time

Re: [Caml-list] slightly OT: anyone reading this list with Mutt?

[caml-list]

Eric Cooper <ecc@cmu.edu> writes:

> When I list-reply to a message on this list, my outgoing message
> header gets set to
>     caml-list@yquem.inria.fr, caml-list@inria.fr
>
> When I notice it, I can manually delete one, but I often forget,
> resulting in a duplicated post.  

> Does this happen to anyone else, and

Yes, to me.

> is there a fix?

The mail client should interpret the List-ID header field (present in
mails going through the inria list), know from that, that the mail came
from a list and reply to the list. Perhaps there is a extra command in
mutt which does this (like "reply to list").

Unfortunately this doesn't work if you have an imap server (like
cyrus) which does duplicate elimination. Then the first mail that
arrives (usually the copy adressed to you personally) doesn't carry
the List-ID and the other copies you don't see at all :-).

This is fundamentally broken and cannot be fixed, except
heuristically. I've programmed Gnus to respect List-ID until I found
the problem with the duplicate elimination. Then I stopped trying to
bring sense into 'To:', 'CC:', 'List-ID', 'From:' whatever. There is
no way to give any specific meaning to those fields. I even got
"newsletter" mail that was apparently adressed to the sender (and then
my Gnus always sets 'From' to that adress on reply: Arrgs!

The only way I can see to handle this, is, to filter incoming mail
with procmail, detect the list address in ANY of CC, From, To and tag
the mail with a "list context". Replying should detect the list
context and address all mails belonging to a list context to the list
in question (one can use List-ID for the list-context or have a
per-folder configuration).

I know religious wars are made from how E-Mail list headers are done
right. I don't want to start any, my comment should be construed as
humble practical advice only. 



Regards -- Markus

Re: [Caml-list] slightly OT: anyone reading this list with Mutt?

[ls-ocaml-developer-2006]

caml-list@inria.fr writes:

> Eric Cooper <ecc@cmu.edu> writes:
>
>> When I list-reply to a message on this list, my outgoing message
>> header gets set to
>>     caml-list@yquem.inria.fr, caml-list@inria.fr
>>
>> When I notice it, I can manually delete one, but I often forget,
>> resulting in a duplicated post.  
>
>> Does this happen to anyone else, and
>
> Yes, to me.

Please ignore me. I seem to have an inclination to put my foot into my
mouth in public recently :-(. The problem I described is related but
different.

The fix, though, to locally process incoming mail with procmail to
"fix" the headers would be valid.

Regards -- Markus

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

[Martin Jambon]

On Thu, 15 Mar 2007, ian wrote:

> Gabriel Kerneis wrote:
> > Le Thu, 15 Mar 2007 09:09:17 +0100, Maxence Guesdon
> > <maxence.guesdon@inria.fr> a écrit :
> >> This page and its english version were ported to the new site some
> >> months ago:
> >>   http://caml.inria.fr/resources/doc/guides/guidelines.fr.html
> >>   http://caml.inria.fr/resources/doc/guides/guidelines.en.html
>
> Merci!  C'est exactament ce que je cherche!

Another way is to inspect the source code of the standard library (with
ocamlbrowser) and use the same style.


Martin

--
Martin Jambon
http://martin.jambon.free.fr

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

[Richard Jones]

On Wed, Mar 14, 2007 at 05:25:37PM -0500, ian wrote:
> Say I have a function called "solveHardProblem". 

Ack!  studlyCaps is horrible and unreadable (I know - I'm currently
involved in a project which uses them).  Try "solve_hard_problem"
instead.

> 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.

You've been taught wrong.  There are some studies that show that long
functions actual reduce error rates - see Steve McConnell's book Code
Complete for references.

> Is it wrong to use a module to hide those functions if the module
> signature will contain only that of solveHardProblem?

Not wrong at all.

> 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?

You don't need to create a separate .mli (in fact, you sometimes
can't).

Rich.

-- 
Richard Jones
Red Hat

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

[Jon Harrop]

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