Re: [Ocaml-lib-devel] ExtLib v0.1o

[William D. N. <wne...@cs...>]

On Tuesday, March 4, 2003 Nicolas Cannasse yammered thusly:

> For a langage-design problem, you're using an editor solution... 

Not really.  I believe the proper design is to use fully descriptive
identifiers.  I merely suggest an editor feature as a possible aid to
those who don't want to type long names.

> I think you're totally wrong here, because as we can choose, they
> shouldn't be *any* long, commonly used identifier.

You know, years ago I might have agreed with you -- back when I wrote
code only for myself.  But now that I write code in an environment
where your code has a life that includes a number of other people, and
code reviews are often performed (and often painful), I can't disagree
more.  For me (and I'd wager a great number of people), code is read
by humans far more often than it is written by humans, and reading
identifiers like MutableList or InitializeCryptoVariable makes reading
that code much easier than MList or InitCV.

> Main arguments against MList are :
> 
> 1) this is too short for COAN , can cause name clash
> answer : we're writing a "standard" library, we have priority on
> module names (just after the official ones)

The only "priority" we are given is by the people who would use our
library.  And if our names clash with other libraries that those users
find more valuable, our priority vanishes.

> answer2 : there currently no COAN around 

Does this mean that we shouldn't look forward to what is likely to
happen with a COAN?  Should we not try to use a design that will "play
nice" with a wide array of future libraries?

> answer3 : the -pack compiler option can resolve such problems

True.

> 2) this is not understandable in the first sight
> answer : why should it be ? I mean, if you're reading a Java
> program without knowing at least a bit of the JDK, you're not going
> to understand it like you would read an english text.

Well, I've never programmed in Java (well that's not entirely true, I
wrote one silly little program about four years ago), but I have had
to grade a few programs written in Java, and I was very pleased to
find code like:
    parser.whitespaceChars()
    g.modInverse()
    doChineseRemainderThm() 
    [although this last one isn't built into the language]

Identifiers like that made these programs far easier to read than
something like:
    parser.wsChars()
    g.mInv()
    doCRT()

> answer2 :  Programming is matter of syntax and semantic rules,

Only in isolation (or in theory) is programming solely a "matter of
syntax and semantic rules".  Unfortunately, programming rarely occurs
in isolation (or in theory).

> keeping shortly named modules is helpful when reading problems as
> it keeps the source code compact.

I don't think I would ever agree that an overly shortened identifier
makes reading code easier or more pleasant than a fully descriptive
identifier (speaking generally, of course).

> answer3 : It's only a problem for beginners, and they can still
> look at the doc to see what is MList

I'd change that to say, "It's only a problem for those who are not
especially familiar with the module/function in question."  I wouldn't
call myself a beginner, but overly short names still make reading code
more difficult for me...

Now then, the only argument so far against MutableList (or similar
fully descriptive name) is that it is too long.

answer 1:  Get an editor that supports keyboard macros or
abbreviations.  At the very least, get one that supports find/replace.

answer 2:  let mlBlah = MutableList.blah

Now, before you point out that these arguments could both be used to
support your position as well (well, half of answer 1 and all of
answer 2), I would suggest that they lend more weight to the
descriptive name argument.  This is because I believe that while a
user should be free to make the language less descriptive for the sake
of typing fewer characters, it should *not* be the user's
responsibility to bring the language up to a basic level of
readibility.  That responsibility should remain with the
language/library developer.  (Hmmm...that thought was a lot harder to
put into words than I figured it would be...I hope I got the point
across).

> Naming conflicts should be resolved by arguments, not by a vote.

Well, they should be resolved by arguments followed by a vote.  I read
your arguments, I read Blair's, and I considered my own (although I
should have shared them earlier), and then I voted... what's wrong
with that?

William D. Neumann

---

Now, a few words on looking for things. When you go looking for
something specific, your chances of finding it are very bad.  Because
of all the things in the world, you're only looking for one of them.
When you go looking for anything at all, your chances of finding it
are very good. Because of all the things in the world, you're sure to
find some of them. - Daryl Zero, Zero Effect