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

[Michel Fortin]

On 2011-01-11 20:28:27 -0500, spir <denis.spir at gmail.com> said:

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

I support this too. Names should be easy to read.

That said, I'm not exactly sure about what you mean by this "use 
international words" recommendation. I really don't get why "section" 
would be better than "slice". Words that exists in other languages 
don't always have the exact same meaning as in English, so they might 
also be more confusing to an international audience. I'd stick with the 
"choose a meaningful word" rule.


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