Naming things in Phobos - std.algorithm and writefln

[Michel Fortin]

On 2009-08-05 03:29:11 -0400, Daniel Keep <daniel.keep.lists at gmail.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?
> 
> This is a specious argument.
> 
> splitter's only purpose is to return an instance of a Splitter struct.
> You can't call it "splitLazily" or "splitLazy" because that implies that
> the function is doing work, when it really isn't.

I agree, those aren't very good names.

> Following this line of reasoning, all structs should be renamed to verbs.
> 
> "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.

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.

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

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?).


>> And what about the "array" function? Wouldn't it be clearer if it was
>> "toArray" so we know we're preforming a convertion?
> 
> Same reasoning as above.  toArray is also fine; it's possibly more in
> line with other conversion functions.
> 
>> 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".
>> 
>> [1]: http://prowiki.org/wiki4d/wiki.cgi?DProgrammingGuidelines>
> 
> 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'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?

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.

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

	write     ->  write
	writeln   ->  writeLine
	writef    ->  writeFormat
	writefln  ->  writeLineFormat

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.
	

>> ...
>> 
>> What does everyone thinks about all this?
> 
> I think it's a good idea to have a good style guide; but rules only
> exist to make you think once before you break them.  :)

By "thinking twice" you should be able to come with a good 
justification; and if you can't then you should follow the rules. 
That's fine by me.


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