Naming Stdlib Functions (and Naming in General)

[ozra]

I've held of this issue long enough, might as well open it now to get as much thought on it as possible.

"Rules" for this issue

• There's a related issue: #45 considering only types. This issue will mainly focus on stdlib-function names, but can be more holistic and generic in discussion.
• As the majority of coders are non-native-english speakers, but english is the lingua franca atm, Onyx identifiers shall be named with a "programmer-pidgin-english" as primary language in mind. That is "receive" is not a word, but "rcv" is, "unique" is not, but "uniq" is - arguments against this ideal are welcome too.
• All suggestions should be backed up by prior art (usage elsewhere) and/or motivation out of "perception of others"-perspective to add value and quality to the discussion.
• Suggestions begins with specific functions of course, and when the list starts to build up, namings will be compared so that a sort of unified pattern can be found.

Current names in the Crystal-sphere for types and functions in stdlib can be found on Crystals web-site: http://crystal-lang.org/api. Onyx simply wants the "cleanest naming" possible - inspiration can come from any language, lib or novel invention.

List will be updated here in OP when some kind of consensus (or dictating intervention) is reached, for "current state of suggestions". It will be open for change all the way until 1.0 is reached (will be a while ;-) ).

[stugol]

I'm not sure about rcv. It's nowhere near as clear as receive. It doesn't make the language any more readable for non-English-speakers; but does make it less readable for English-speakers.

I'm not sure where you're getting this "majority of coders" statistic from. If we assume generously that Americans, Australians and Scotsmen can speak English, I count at least seven native-English-speaking countries; probably more - my geography is worse than my history and my maths, and they're pretty damn awful. (this webpage lists 23 countries, when you consider that Scotland is a different country to England.) Plus many countries, such as Wales and your own country, commonly speak "good" English as a competent second language.

Add to that the fact that English is the de facto language of the Internet and of programming in general; and I fail to see the benefit of replacing perfectly good English words with abbreviations that mean nothing to anyone, whether English-speaking or not.

Sometimes abbreviations serve a purpose, of course, to reduce verbosity and such. bool, int and such are immediately recognisable, and expanding them to their full words would achieve nothing. But rcv is abbreviation for the sake of it, and actually harms readability.

I'm in favour of operators, however. channel >> x is far preferable to x = channel.receive.

[stugol]

Also, you seem to be proposing to rename stdlib functions. Is that wise, given that we need to support Crystal interop?

Certain functions could do with renaming - for example, I convinced Asterite to rename inject to reduce - but the only safe way I can think of is to add an alias, and let the programmer choose.

[ozra]

1.

• The example: rcv is used in several programming languages as de-facto term for receive - mind share for common functionality grows quickly, that's why people can remember fprintf without thinking.
• People comprehending english:
  • Estimated 8% - 40% - very rough figures, it means that between 60% and 92% of the world don't understand it at all.
  • "In 2012, excluding native speakers, 38 percent of Europeans consider that they can speak English"
  • Programmers are generally thought of as knowing English better than the general population. Programming is becoming the job (as processes are automated, manual labour positions disappear, new coding positions appear). Programming becomes more and more important in all scientific fields, and a (arbitrary example) Persian biologist might have different priorities than to learn English (curing cancer for instance). It's not difficult to see that the number of programmers not knowing English will increase quickly in the future. The world is big. English is small in comparison to for instance Mandarin, Hindi, Spanish - and more importantly as to the first point: "in comparison to other languages in general".
  • All this taken in to account "English-ish" is still preferred imo, however more easily spelled terms like "rcv" and "uniq" can have a positive impact on work flow. Imagine Swedish being de-facto "code language", try remembering "mottag". It's not a "word" to you, it will simply be a learned term for "receive". "Was it one or two 't' now again?" Further exemplifying: "definiera" ("define"). "Damn, where did the 'i' and the 'e' go now again?". Same scenario as for 'receive' - "or was it 'recieve'?".
  • As a parentheses I suspect the words with frankish/french/latin origin, especially as to spelling, are the main culprits with their wovel chains from hell ('queue', 'unique'), while words of germanic origin usually are more on the point - spelling wise.

2. Just like Crystal, C++, and most languages, name-mangle identifiers internally, so does Onyx, it also adds a layer of "knowledge" of translations of manglings between Onyx and Crystal nodes, so the renamings are transparently handled for the user.

Aliases are definitely an option, but taints the namespace unnecessarily, especially since it becomes harder to understand that two functions are really the same when looking at different projects using different names. The user can of course always define aliases themselves, but having them already available lower the threshold to utilize non-official stdlib-names.

Your example is one of those things that speak for this: reduce is much better than inject. Since Crystal is still "stick-to-Ruby-ways"-centric, it may be hard to convince the community liking the Ruby-approach to get things changed, and then it's better that names can be decided for Onyx without concern, and still maintaining full transparent interoperability.

Docs for Onyx for stdlib will of course be generated separately and the babeled names will be in those docs.

[stugol]

What is a "wovel chain"?

You make good points, but I still don't like rcv. Further, being a native English-speaker myself, it is my considered opinion that everyone should learn and speak English ;)

[ozra]

That should have been "vowel" :-) Seems consonants are problems for us non-english too, haha.

Just like we believe (that's another hard word! I always type "beleive" first) everyone should speak the language of Oden and Tor, but it won't happen, haha.

'rcv' was just an example though to highlight the motivation, so don't get hung up on that in particular ;-) As you mentioned, places where such a term would be used are places where an operator is more likely to be used.

[stugol]

Isn't it "Odin and Thor"? Gah, I hate the fact that there is more than one human language!

[ozra]

Why you infedelic christan heredic! B-)

Languages are exciting - knowing more of them lets you think in different ways. I only know a few marginally, but it's enough to spur the thoughts in to new directions.

Consider the English word "computer". When the term was coined, these machines did just that: "computed". In Swedish the term didn't come about until when computers already could store and process lots of data, hence it's called "dator". In french it came in to wording later yet, and at that point it had evolved to a machine managing and structuring work, data, etc. and there it's called "ordinateur". Had it come in to the anglo sphere today it would probably be named "chat- and porn-device", hahaha.

[stugol]

lol, chat and porn device. Sounds about right.

Incidentally, I'm not a christian either ;)

[ozra]

Haha, didn't think you were, just kidding a bit :-)

[ozra]

Ideas, again, for type reasoning "methods and functions" with corresponding Crystal-construct to the right of eq-sign - forgot where the last discussions ended up ("wrong" issue probably), so chip in again:

decl-type Typ or maybe dtype Typ = typeof Typ - because you get the "declared" or compile-time type. obj.inst-type or obj.itype or obj.curr-type = obj.class - because it gives the current type of the instance obj.of? Typ or obj.in? Typ = obj.is_a? Typ - because it's "short and sweet" and more accurate. obj.implements? #some-foo = obj.responds_to? :some_foo - we won't obscure the fact that methods are member-functions - there's no fictive "message-passing".

[stugol]

Haha, didn't think you were

Oh? Out of curiosity...what did you think I was?

of? is fine. implements? is only fine if you can also pass it a module name:

say [1].implements? :first              -- true
say [1].implements? :Enumerable         -- true

typeof is better than the suggested alternatives. type may be better than inst-type.

[ozra]

Oh? Out of curiosity...what did you think I was?

No opinion, assumed atheist / agnostic, like most people in general in Swe, UK, etc. countries.

of? is fine. implements? is only fine if you can also pass it a module name:

That's a great idea, very fitting - I'll look into it.

typeof vs. type is not very revealing of what typing they'll give you. Furthermore type is not to uncommon a generic identifier to use for a member-var / method, so not to keen on that option as of now.

[stugol]

I doubt "most" people in the UK are atheists. The churches and other similar centres of stupidity in my area seem to have no shortage of patrons. But yes, I make it a point not to believe unsubstantiated claims of any sort, which makes me atheist. (Being agnostic simply means you give equal credence to nonsense as to sense. Not a position to aim for, really.)

I don't understand what's wrong with typeof.

[ozra]

afai-concerned atheism is a belief too, making the agnostic the only truly scientific point of view. That said I'm atheist (even though praying to the Asa-gods for the psychological shortcut to benefit from mentalization), and I'm all for any one believing anything as long as it's beneficial to the individual. And that said, let's drop toxic subjects in a tech forum ;-)

typeof - "does it give the declared type / compile time type or the type in the current position at run time". It's not very clear when compared with type. typeof is not used that often that a more explicitly named "decltype" couldn't be used imo.

[ozra]

I think this is a bit too pre-emptive.

As long as is possible, they should be named as is in Crystal lib, for minimum confusion.

For functions that for historical reasons have fucking bad names (TM), we will simply recommend (and show in docs) an official alias for Onyx.