Naming things in Phobos - std.algorithm and writefln

[Michel Fortin]

On 2009-08-05 11:11:20 -0400, Daniel Keep <daniel.keep.lists at gmail.com> said:

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

I do Objective-C, so I know a lot about long names. :-) What's great 
about them is that they make the code a lot very readable (especially 
with Objective-C where methods read like a sentence). What's less great 
is that they're long to type.

(An no I don't want to see sentense-long funciton names in D by the 
way, the D grammar isn't appropriate for that.)


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

My take is that the sentenses are too long, not the actual words. Would 
the legalise be more readable if it were using abbreviated words? I 
believe it'd be worse.

Same with code. If you put too much in a statement it'll become hard to 
decipher.


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

You mean that a good name is one that begins with a word followed by 
half-conventions from various other languages merged together?

That other languages use some other convention isn't really a 
justification for naming D functions against the D conventions.


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

But can they be used consistently? In C, you have a lot of math 
functions having the suffix "f", and it has nothing to do with them 
being formatted.

Can we restrict the usage of the suffix "f" to mean "formatted" in the 
guidelines? Can we restrict the usage of the suffix "ln" to mean "line"?

Also, that convention doesn't scale. There is a very limited number of 
short suffix. Either you'll start reusing them for other things, or 
you'll have a bunch of legacy functions using a short prefix and new 
functions with more explicit names.


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

> [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.

True indeed. But D allows symbol renaming in the import declaration. If 
you're going to use a function a lot, you can rename it to something 
shorter for a module. If you're not using it much, the long name will 
be more explicit.

	import std.stdio : ofln = outputFormattedLine;


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

Does this justify the sufix being lowercase. It's a different word 
after all. Why not "writeFLn"?


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

I disagree, it's descriptive up to until "fln". At least that's my opinion.

Don't misunderstand me: I like writefln for it's shortness and because 
it's easy to write. But I don't see how I can justify the name without 
adding some arbitrary exceptions that look dumb.

Perhaps I should just leave the names alone in Phobos and let Walter's 
style guide do the job. It says: "Names formed by joining multiple 
words should have each word other than the first capitalized." which 
means you can write names as you like as long as it's not words 
concatenated together.
Source: <http://www.digitalmars.com/d/2.0/dstyle.html>

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