Naming things in Phobos - std.algorithm and writefln

[Daniel Keep]

Michel Fortin wrote:
> On 2009-08-05 03:29:11 -0400, Daniel Keep <daniel.keep.lists at gmail.com>
> said:
>> "makeSplitter" is OK, but needlessly verbose.
>>
>> I think when you have a function whose only purpose is to construct
>> something, or is strictly or conceptually pure, it's OK to use a noun
>> for its name.
> 
> Perhaps this rule should be added to the guideline then. But as it was
> said countless times in the all the threads about properties, many nouns
> are also verbs in English, and they can easily create confusion in this
> situation.

Yes, there are lots of nouns that are also verbs but "splitter" isn't
one of them.  Just because they exist doesn't mean you can't ever use
nouns without qualification.

> Calling directly the constructor of Splitter would be great, but alas
> you can't deduce struct template aruments from its constructor and have
> to rely on a separate function.

My point was that there would be ZERO difference assuming we could;
arguing that just because it's implemented using a function that it must
be extra verbose is just silly.

> "makeSplitter" is the less consusing one in my opinion.

It's more accurate but, as I said, needlessly verbose.  "splitter" is a
noun and it's hard to even deliberately think of ways to misinterpret
it.  I mean, we use "sin(x)" without problems although it could also
have been written "computeSineOf(x)".

Except, of course, then you'd have a hoard of angry numerical
programmers knocking on your door with torches and pitchforks.

> Altenatively, we could rename "splitter" to "split". After all, the
> documentation says "Splits a range using another range or an element as
> a separator." If you want an array, you write split(...).toArray(), or
> perhaps better would be to have the resulting range implicitly-casted to
> an array when needed (but are implicit casts still in the pipe now that
> we have alias this?).

No, naming it "split" implies that it's performing the "split" action on
its arguments, which is *isn't*.  Implying that it does *anything* in
the function name is misleading since nothing actually takes place until
*after* the function has returned.

>>> ...
>>
>> I think that's a problem with the guidelines.  Anyone trying to turn D
>> into Java should be shot.  It's not clear what "fln" means, true...
>> until you look up ANY output function with a f, ln or fln suffix and
>> then it's obvious.
> 
> Please, don't make unsupported accusations as an excuse to shoot people.
> Instead, you should say what you dislike about Java and explain why. (My
> guess is you find System.Out.println too long.)

I was attempting to be jovial. [1]

Java and, to a lesser extent, .NET have this serious problem where all
of the names are needlessly long and verbose.  This makes writing actual
code tedious and annoying.  No, I do not use an IDE and I shouldn't NEED
autocomplete to be able to write code efficiently.

Also, making code longer means less of it fits on a line, less on a page
and most critically of all: less in your brain. Look at legalese: it's
incredibly accurate but also almost impossible to read.  I've found that
it takes so long to read a sentence that by the time you finish, you've
forgotten what it was about.

Just because a name is unambiguous doesn't automatically make it good.

writefln is a good name because the root indicates what it does "it
writes to something", the f comes from printf and ln is used in a few
languages.

What's more, even if you don't know what those suffixes mean initially,
because they're used *consistently*, once you learn it you can apply it
all over the place.

And best of all: it's short to type. [2]

> I'm tring to see how I can adapt the guidelines to accept this function
> ("writefln") and I can't see any sensible rule I could add. Any idea?

"Short suffixes are good when applied consistently across multiple
symbols."?

> Alternatively, "writefln" could be an exception to the rules, but then
> the exception would need a better rationale than "it shouldn't look like
> Java". I mean, if Phobos makes unjustified exceptions to its naming
> conventions here and there for no good other reason than "it looks
> good", it breaks the concistency and makes function names less
> predictable and less readable.

As I indicated above, it's descriptive, consistent and short; a great name.

> But it'd be easier to rename the functions to fit the convention:

I find that supposition hard to accept.

> ...
> 
> That way, if someone writes logging functions one day that takes
> formatted strings in the same way, he can reuse the convention:
> 
>     log
>     logLine
>     logFormat
>     logLineFormat
> 
> instead of "log", "logln", "logf", and "logfln". If you create a hash
> function, you can reuse the pattern too:
> 
>     hash
>     hashLine
>     hashFormat
>     hashLineFormat
> 
> instead of "hash", "hashln", "hashf" and "hashfln". And it goes on.

How is this an improvement?  If we accept that people know what the "f"
and "ln" suffixes mean (and given that they will be exposed to this in
the course of writing a Hello, World! program), what benefit is gained
from increasing the length and complexity of the identifiers?

Saying you can re-use the convention is irrelevant because the exact
same thing can be said of the shorter suffixes.

---

[1] I mean I was joking about you trying to turn D into Java.  People
who ARE trying to turn D into Java *definitely* need to be shot.  Then
buried upside-down at a crossroads with a steak through their heart.
Then burn and salt the earth afterwards just to be safe; you can't take
your chances with that sort of malignant evil...

[2] And just to pre-empt it: this doesn't mean 'ofln' is a good name for
an output function.  Doesn't mean it's bad either; that depends on context.