On 2011-01-11 20:28:27 -0500, spir <[email protected]> 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
[email protected]
http://michelf.com/
