Naming things in Phobos - std.algorithm and writefln

[Daniel Keep]

Benji Smith wrote:
> ...
> 
> The thing about one-letter abbreviations is that they mean different
> things in different contexts. An "f" might mean "formatted" in a
> "writefln" function, but it means "file" in an "ifstream" and "floating
> point" in the "fenv" module.

I don't think this applies.  Firstly, I was talking about suffixes, not
abbreviations appearing in other parts of a name.  Secondly, the
convention is: "an f suffix on an output method means formatting."

That doesn't conflict with fenv at all since the f there isn't a suffix
and "env" has nothing to do with output at all.  Besides, even if you
thought the "f" was "formatter", you'd be quickly dissuaded when you
looked in the docs and saw "fenv.h is the standard header providing
access to the floating point environment."

The ambiguous case is ifstream which could be interpreted as "input
formatted stream" if you were really trying.  But here's the kicker:
"ifstream" is a bad class name ANYWAY because it's all lowercase and
highly ambiguous.

A sane name for ifstream would be FileInput which drops the redundant
"stream", expands both the "i" and "f" to their full names and is only
one character longer.  Win!

Finally, I don't think you can just toss context out the window
completely and say 'but there's an f; it could mean anything!'.  No,
interpret it based on context and all will be well.

If you have an output function on a file with an 'f' suffix, odds are it
means "format".

If you have a logging function on a logging object with an 'f' suffix,
odds are it means "format".

If you have an inverse square root function on a math object with an 'f'
suffix, odds are it really doesn't mean "format".  Given we have
overloading, my guess would be "fast", and then I'd check the docs.

> In those cases (and in many more), there's no convention than can be
> reused. You just have to memorize stuff. Memorization was a perfectly
> acceptable solution back in the days of C, when standard libraries were
> small. But I think any modern standard library, with scores of modules
> and hundreds (or thousands) of functions, needs a better strategy.

You can't not memorise stuff.  You have to look up the docs if you don't
remember what a function's arguments are or what its semantics are
irrespective of the name.

> Coming from a Java background, I much prefer to give up terseness in
> favor of clarity. Though I recognize that verbosity has its own
> pitfalls, I think it's the lesser evil.
> 
> --benji

It's alright; enough electro-therapy will cure you of your Java
tendencies.  We CAN save you!