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

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

[David Allsopp]

> 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.
Horrible and unreadable? We seem to be forgetting that camel notation versus
underscores is entirely a matter of taste... I have no problem reading camel
notation and find underscores ugly (not to mention harder to type than
caps). I've always found the argument "the standard library uses this
notation" to be a very weak argument typically coming from more senior
programmers who're clutching at straws to justify their opinions ;o)

I'm glad that, most of the time, the only standard library functions I use
with underscores are {type}_of_{other type} or {to|from|of}_{type} so don't
happen too often.

(amusing aside: I once worked for a company that mixed the two... giving
solve_Hard_Problem which was particularly tedious!!)

<snip>

> You don't need to create a separate .mli (in fact, you sometimes
> can't).
Eh? When does ocamlc -i Foo.ml > Foo.mli ever fail? I too always pair a .mli
file with a .ml file even if the signature is exactly the same.

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

[Richard Jones]

On Thu, Mar 15, 2007 at 11:08:28PM -0000, David Allsopp wrote:
> > 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.
> Horrible and unreadable? We seem to be forgetting that camel notation versus
> underscores is entirely a matter of taste... I have no problem reading camel
> notation and find underscores ugly (not to mention harder to type than
> caps). I've always found the argument "the standard library uses this
> notation" to be a very weak argument typically coming from more senior
> programmers who're clutching at straws to justify their opinions ;o)
> 
> I'm glad that, most of the time, the only standard library functions I use
> with underscores are {type}_of_{other type} or {to|from|of}_{type} so don't
> happen too often.
> 
> (amusing aside: I once worked for a company that mixed the two... giving
> solve_Hard_Problem which was particularly tedious!!)

noIReallyThingYouReWrongAboutThisOne.

> > You don't need to create a separate .mli (in fact, you sometimes
> > can't).
> Eh? When does ocamlc -i Foo.ml > Foo.mli ever fail? I too always pair a .mli
> file with a .ml file even if the signature is exactly the same.

I meant for defining the type of just an inner module on its own.
It's generally a good idea to define types of interfaces in .mli
files.

Rich.

-- 
Richard Jones
Red Hat

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

[Quôc Peyrot]

On Mar 15, 2007, at 4:48 PM, Richard Jones wrote:

> On Thu, Mar 15, 2007 at 11:08:28PM -0000, David Allsopp wrote:
>>> 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.
>> Horrible and unreadable? We seem to be forgetting that camel  
>> notation versus
>> underscores is entirely a matter of taste... I have no problem  
>> reading camel
>> notation and find underscores ugly (not to mention harder to type  
>> than
>> caps). I've always found the argument "the standard library uses this
>> notation" to be a very weak argument typically coming from more  
>> senior
>> programmers who're clutching at straws to justify their opinions ;o)
>>
>> I'm glad that, most of the time, the only standard library  
>> functions I use
>> with underscores are {type}_of_{other type} or {to|from|of}_{type}  
>> so don't
>> happen too often.
>>
>> (amusing aside: I once worked for a company that mixed the two...  
>> giving
>> solve_Hard_Problem which was particularly tedious!!)
>
> noIReallyThingYouReWrongAboutThisOne.

To quote gaim/HACKING:

"Coding styles are like assholes, everyone has one and no one likes
anyone elses." - Eric Warmenhoven

-- 
Best Regards,
Quôc

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

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

[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

[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

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

[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

[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: 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

[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

[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

[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

[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

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