Naming things in Phobos - std.algorithm and writefln

[Michel Fortin]

On 2009-08-05 08:15:49 -0400, Don <nospam at nospam.com> said:

> Michel Fortin wrote:
>> In std.algorithm, wouldn't it be clearer if "splitter" was called 
>> "splitLazily" or "splitLazy"? "splitter" is a noun, but as a function 
>> shouldn't it be a verb. "makeSplitter" or "toSplitter" perhaps?
>> 
>> And what about the "array" function? Wouldn't it be clearer if it was 
>> "toArray" so we know we're preforming a convertion?
>> 
>> As you know, I tried to write some guidelines[1] for naming things in 
>> D. Those guidelines looks well at first glance, but then you look at 
>> Phobos and you see that half of it use some arbitrary naming rules. 
>> Take "writefln" for instance: following my guidelines (as they are 
>> currently written) it should be renamed to something like 
>> "writeFormattedLine".
> 
> There should be an exception for functions which are analogous to C 
> functions and have well established names in C. (eg, printf). Probably 
> for famous functions in other languages, too.

That I mostly agree. "printf" can stay as it is in D. There's already 
rule for that in the guidelines:

"""
When writing bindings for code in other languages or system functions, 
types, variables, constants, functions, and arguments can keep their 
original names.
"""

> writeln() comes from Pascal, analogy with printf gives us writefln(). 
> So that one's OK.

That's an explanantion, but is it really a justification? Tell me why 
it's OK. Is there any significant advantage in borrowing the "writeln" 
Pascal function name over using the D convention to name the function, 
say "writeLine"?

I'm thinking aobut it and realizing that "writeln" and/or "writefln" 
are *the* functions you always see in hello world programs and other 
introductions to D. I'm wondering: if we can't follow a naming 
convention for these, then how can you tell people to follow the 
conventions elsewhere?

It's not like we have been following a convention that holds across 
many languages (unlike the math functions, more on that later). The 
only sort of half convention I see from a wide range of languages is 
that functions named using variants of "print", "write", "echo", or 
"put" usualy write to the standard output when called in a global 
context or on a global object representing the console[^1].

 [^1]: Based on reading many hello world programs from
       <http://helloworld.googletoad.com/>,
       considering only command-line programs.


>> I could take a look at std.algorithm and other modules in Phobos to 
>> list inconsistencies with the guidelines. From this we could make 
>> improvements both to the guideline document and the API. But before 
>> going too deep I think we should start with a few examples, such as 
>> those above, and see what to do with them.
>> 
>> What does everyone thinks about all this?
> 
> Yes, this is great. A review process would be very valuable.
> Please check the names in std.math. For the most part I have taken the 
> names from the IEEE754-2008 standard, but please make suggestions. As 
> we move towards finalizing D2.0, that module should be one of the first 
> to have its interface frozen.

Great... well, for math functions I think binding them to a 
cross-language standard makes sense. I mean, should we really rename 
"sqrt" to "squareRoot"? And what about "lrint", rename as 
"roundToNearestLong"? Renaming would make code more readable and 
function names more guessable for sure (especially with IDEs with 
suggestion boxes: you write "round" and then you see a list of the 
available rounding algorithms). But using these long names would make 
it harder to convert programs to D. I'm thinking that perhaps we could 
alias the standard names to our functions so that both names are valid. 
I'm not sure what is best here.

Anyway I'd like to have a look, but it appears like I'd need to be an 
IEEE member to download the final standard. What's intriguing is that I 
found an old draft from 2007 at 
<http://www.validlab.com/754R/nonabelian.com/754/comments/Q754.129.pdf>, 
and it doesn't even mention "sqrt", it has "squareRoot" instead. So I'm 
a little confused right now: you said you took the most names from the 
IEEE 754-2008 standard, is the final standard different or did you just 
take some names (like isNaN) from the standard while keeping the C name 
for most others (like sqrt)? (I'm just trying to understand here.)

-- 
Michel Fortin
michel.fortin at michelf.com
http://michelf.com/