Understandable names

[bramtayl]

Base Julia is full of abbreviations. Functions with names like iscntrl are inscrutable. I think, before it's too late, that Julia should make every effort to be written in plain English. To this end, I think that rules like this should be put into effect:

No abbreviations should be used in base julia for any words shorter than 10 (or so) characters
All words should be separated by _

[johnmyleswhite]

I'm sorry, but this kind of sweeping issue isn't credibly actionable. Please stop opening things that are so broad.

[ScottPJones]

@bramtayl Might be better to 1) make a list of at least the worst cases 2) write a PR to add new, more understandable names (including deprecating the inscrutable abbreviations) 3) wait for the fireworks!

[JeffBezanson]

The story of picking function names is much more complex than you'd think at first. True, iscntrl is pretty obscure, but it's inherited from C. It's possible all of those functions (about 15 of them) could be replaced by a single character-class-querying function.

We also have an avowed policy of avoiding underscores, as it tends to produce overly long names and less-well-factored functions. For example print_shortest(x) (which we currently have, unfortunately) seems worse to me than, say, print(x, shortest=true).

So I think these have to be taken on a case-by-case basis. To that end, it's certainly possibly there are a few especially obscure names we can fix.

[ScottPJones]

We also have an avowed policy of avoiding underscores

@JeffBezanson Where is that policy? That doesn't seem to be what Julia Docs says:

Word separation can be indicated by underscores ('_'), but use of underscores is discouraged unless the name would be hard to read otherwise.

The statement in Julia Docs seems reasonable, however, avoiding underscores by simply removing them flies in the face of research that has been done into readability of names. I believe that language design should be data driven, and think it would be good to take that research into account in julia.

For things like your print example, where there is a better way, with keywords or the type system, I definitely agree, it's would be good to get rid of the composite names.

Another thing is to adopt hard to understand names because they came from C (from back in the day when linkers could not handle more than 8 characters in a name, file names were limited to either 8.3 (C/PM & MS-DOS), or 14 for Unix), Matlab, or R. I've been told a number of times that arguing that something should be done like some other language was not a good reason to do something in julia, however it is has been used as an excuse for those inscrutable names.

That's sad, because julia can do so much better, with it's great (and getting better) type system and multi-dispatch.

How about something like: ischar(Control, x) or ischartype(Control, x)?
(with abstract CharClass ; immutable Control <: CharClass ; end)
A package could define iscntrl(x) = ischartype(Control, x) if they really wanted to.
Looking at Base, only 4 of those functions are even used, isspace is used in 4 files, 11 times total,
isprint is used twice, in 2 files, isupper and islower are used once each in 1 file.

Would people accept a PR that added ischartype, with say just the short forms for isspace, islower, isupper, isprint and isdigit (which I saw some in packages), deprecating the rest, like iscntrl?
isblank was deprecated already.

[bramtayl]

I definitely think that is is good have "well-factored functions". And I understand how it would be easier to inherit C function for users familiar with C.

One thing to do would be to go through Julia and make the three changes below:
-No words longer than 10 or so characters (for example, "short" instead of "abbrev.")
-No abbreviations at all
-All words should be separated by _

And in the process, building "well-factored functions" groups where possible, and maintaining C compatibility if deemed necessary, all on a case by case basis.

From this thread, isupper, isprint, islower have the words supper, sprint, and slower within them. Unwary users could be confused by all the apple products referenced in Julia! This ambiguity would be avoided by is_upper, is_print, and is_lower.

[eschnett]

Here's an example: The function to remove a file is rm, taken from the Unix shell syntax. However, rm is strictly more powerful as it also includes the functionality of Unix rmdir. The same function is called remove in other languages (including C!), so this could be an entry on your list.

Note, however, that there is a group of similar functions (including e.g. mkdir, cp, mv, symlink, and a few more), and they should be named in a consistent manner.

[bramtayl]

Unix is a great example of an interface that is completely unreadable because of excessive abbreviation. Regex is another example (and there are great alternatives; see the R package rex).

[StefanKarpinski]

This issue is also mistitled since it's not about syntax at all.

[JeffBezanson]

-No words longer than 10 or so characters (for example, "short" instead of "abbrev.")
-No abbreviations at all
-All words should be separated by _

We are definitely not doing this. This isn't three changes; more like thousands. But the real issue is that as soon as you start trying to apply sweeping policies like this you run into hard decisions over and over. Is rand really so objectionable that it needs to be renamed random? Should abs be absolute_value, and should svd be singular_value_decomp? "Decomposition" is longer than 10 characters; the English language and history of mathematics aren't always convenient.

Is DateTime unreadable? Should it be Date_Time? Does "TCP" qualify as an abbreviation, or is that allowed by custom? Are people better off learning that "eof" in an I/O context means "end of file", or are they better off typing end_of_file every single time? Is NaN an evil abbreviation that needs to be replaced with NotANumber even though it's incredibly standard? Should kron be kronecker_product? Should peakflops be peak_floating_point_operations_per_second?

Another non-obvious point is that when we copy names from C, it's not usually because we're trying to make things easy for C programmers. Rather it's for global consistency --- that is, consistency not just within julia but among software systems. When picking a word for something, one of the first things you ask is whether there is already a word for it, and if so, why not reuse it.

see the R package rex

Isn't "rex" an abbreviation for "regular expression"? Who allowed that?

[mason-bially]

I think before a 1.0 release, the list of all the names could be given a once over. That doesn't seem unreasonable. It might allow a few particularly poor names to be noticed when viewed in a larger context.

But in the long run Julia provides capabilities to create packages which export custom sets of names, heck the package could even be auto generated for the most part. If someone want's a custom set of names then they can provide it themselves.

[ScottPJones]

But the real issue is that as soon as you start trying to apply sweeping policies like this you run into hard decisions over and over

@JeffBezanson You are kind of arguing against yourself here - while I also don't agree with @bramtayl's 3 rules, that's why I also don't agree with the "avowed policy of avoiding underscores".

DateTime isn't a good example, as that already has camelcase to help distinguish the words.
If you follow the convention that all caps implies a constant, that is where underscores are most needed to help separate "words" and make things readable. They aren't needed for camelcase names, by convention module and type names in Julia, as the capital letters are breaking them up.
All lowercase, although more readable than all uppercase (and there are numerous studies on that, from long before computers), do benefit greatly by using underscores if they are long.

I agree with most of your other examples, except the last two - peakflops could be peak_flops, as the common abbreviation is flops, not peakflops, and maybe kron would be more readable as kron_prod (given prod is a common abbreviation for product, assuming that kron is a known abbreviation at least among mathematicians for kronecker).

My recommendation, on a case-by-case basis, would be to look at longer names with _s, and short abbreviated names such as iscntrl, and first see if there is a more julian way of factoring them.
If not, then leave the underscores alone, they do help readability, don't remove them just because of
some policy that somehow underscores are always "bad". Same thing with abbreviations such as TCP
or NaN.

@mason-bially Yes, totally agree. I think short hard to understand names (i.e. to be like Matlab, Unix sh, or C) really belong in compatibility packages. One of the (many) great things about Julia is that it makes doing that sort of thing trivial.