[MLton] extended basis library

[skaller]

On Fri, 2006-10-20 at 10:31 -0700, Stephen Weeks wrote:
> Here's a few thoughts and questions on the extended basis library.
> 
[]
> Second was the convention of following specifications in signature
> with the comment.
> 
>   val intIso : (char, Int.int) iso
>   (**
>    * The isomorphism between characters and character codes.  It
>    * always equals {(ord, chr)}.  Note that the projection part of the
>    * isomorphism, namely {chr}, is likely to be a partial function.
>    *)

This is the ocamldoc style, which comes with a tool capable
of generating documentation of reasonable quality -- enough
for the Ocaml standard library docs. Of course the tool
only works with Ocaml.

> Formatting
> ----------------------------------------
> The code is indented/layed-out in the MLton style, e.g.
> 
>   signature ISO =
>      sig
>         type ('a, 'b) iso = ...
>         ...
>      end
> 
> I'm not a fan of the style (despite having used it for so long) and
> it's only inertia that keeps it in MLton.  I prefer the C-brace style
> 
>   signature ISO = sig
>      type ('a, 'b) iso = ...
>   end
> 
>   structure Iso:> ISO = sig
>      ...
>   end
> 
>   functor MkMonoVectorExt (M : MONO_VECTOR) = struct
>      ...
>   end
> 
> The advantage of this style is that it saves vertical space (no big
> deal) and indentation nesting (a big win).

And the disadvantage of this style is that matching brackets
don't line up correctly. Two other styles are:

signature ISO = 
sig
    type ('a, 'b) iso = ...
end

signature ISO = sig
  type ... end

I personally use all these styles .. could never decide between them.

I think the choice is dictated by size (granularity). I use the
more compact style for small terms, but for large terms
containing many levels of nested terms I'd use the style that
lines matching punctuation up -- for the outermost level,
and switch to the other style for inner terms :)

The one thing I insist on is a consistent indent width
per file: I recommend 2 spaces: it's the minimum, and that's 
what you want for publication and editing, however, I don't
mind code in the repository using different indent widths,
just not in the same file please!

The other 'one' thing I insist on is a total ban
on the TAB character, but that's the same thing:
it is impossible to be consistent with TAB unless
the indent width is fixed .. and fixed at 8.

BTW: for me, compactness is very important.
I once more or less lost my job because I reformatted
all the code in the repository. Some idiot contractors 
decided to use the most expansive style around,
including two blanks lines between C++ class methods,
and I just couldn't read the code at all. I rely heavily
on visual pattern matching when I program, and the
pretty much more stuff I can get on the screen the better -- 
if I have to scroll at all I lose concentration.
For this reason I also use comments very sparingly.

So IMHO vertical space IS important, at least to some
people :)

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