D standard style [was: Re: eliminate junk from std.string?]

[spir]

On 01/12/2011 12:07 AM, Daniel Gibson wrote:
> Am 12.01.2011 00:00, schrieb Andrei Alexandrescu:
>> On 1/11/11 11:21 AM, Ary Borenszweig wrote:
>>> Why care where they come from? Why not make them intuitive? Say, like,
>>> "Always
>>> camel case"?
>>
>> If there's enough support for this, I'll do it.
>>
>> Andrei
>
> Please do, having different naming conventions of functions within the
> standard library makes it harder to remember the exact spelling of a
> function and also doesn't look professional.
>
> +1 vote for making the standard library comply with the D style guide[1]

+1 as well

But while we're at conventions, and before any change is actually done, 
we may take the opportunity to agree not only on morphology, but on 
semantics ;-)

For instance, from online doc:
string capitalize(string s);
     Capitalize first character of string s[], convert rest of string 
s[] to lower case.
Then, use it:
     auto s = "capital";
     s.capitalize();
     writeln(s);         // "capital"
Uh?
Not only the name is misleading, but the doc as well.

For this kind of issue, some guidelines read like:
* perform an action --> action verb (eg capitalise: changes the passed 
string)
* return a result --> named after result (eg capitalised: return new string)
Sure, the func's interface also tells the reader what's actually done. 
But having name (and doc) contradict it is not very helpful. And beeing 
forced to open the doc or even the source for every unknown bit is an 
annoying obstacle.

There are probably other common issues like this. My personal evaluation 
is whether some newcomer can guess the purpose of the func, the type, 
the constant, etc...

I would also vote for:
* full words, except for rare exception used everywhere in programming 
_and_ really helpful (eg OS)
* get rid of obscure, ambiguous, or misleading namings
* when possible, use international words rather than english-only (eg 
section better than slice if everything else equal)

Finally, take the opportunity to make the doc usable, eg:
string format(...);
     Format arguments into a string.
???


Denis
_________________
vita es estrany
spir.wikidot.com