Bikeshed better positional argument names post 1.0

[Ismael-VC]

There are many one letter argument names, that really should be more mnemonic IMHO, things like r/f for replacement, for example. While all objects should be documented someday, good names should be a must for the public Julia API, since method signatures, argument and parameters names are part of this API.

Reference: #25165 (comment)

Positional argument names can be changed at any point without breaking anyone's code. We are at the moment focused on things that need to be changed for 1.0. We can bikeshed better positional argument names until the cows come home post 1.0. - Stefan

[Ismael-VC]

Maybe it's time to follow JuliaPraxis guidelines?

• https://github.com/JuliaPraxis/Naming/blob/master/guides/ShortForms.md#table-of-abbreviations

And expand those guidelines as needed.

[Ismael-VC]

@ararslan The JuliaPraxis guidelines are just a suggestion. But I wonder what do you disagree with. JuliaPraxis guidelines? Enforcing any guidelines? Renaming these variables?

I'm all in for consistency and good naming practices, I'm OK with whatever the guidelines end up being as long as we do have guidelines and we enforce it's use, specially in base Julia (specially since we still have many undocumented code), even if this cryptic variables are properly documented.

[ararslan]

JuliaPraxis guidelines are not official. Any discussion regarding those guidelines should happen on that repo.

[Ismael-VC]

That is true, but I think the very purpose of JuliaPraxis is to become something we all agree becomes part of an official guideline at some point.

What are the official guidelines that we can discuss here then? There is the "official" style guide, but it doesn't mention many things that JuliaPraxis does.

• https://docs.julialang.org/en/stable/manual/style-guide

And some minor stylistic conventions here (which should probably be in the style guide instead of scattered):

• https://docs.julialang.org/en/stable/manual/variables/#Stylistic-Conventions-1

At least I think the intention of @JeffreySarnoff and the people participating in JuliaPraxis discussions was never to start a separate Style guide just for the sake of having something different than what is told in the links above. On the contrary, I believe JuliaPraxis was born precisely from the need of having some place to discuss this bike shedding in order to improve the "official" style stuff without nagging everyone else with non priority "noise".

If the problem is that the style guide is not in this repository, then it would be easy to add those documents here, the issue remains the same, we need to discuss and enforce the agreed official guidelines, sooner or later.

This kind of things may not impact something as crucial as performance, so it's not top priority, I get it, but they impact the users and their development time IMO.

As a mater of fact I'd rather have those style guides here and abandon further discussions on JuliaPraxis, than having JuliaPraxis exist but be considered "not official" and thus being ignored,

Currently what is considered to be "julian" is exported from this repo to the community, though some bad practices are being exported too.

[JeffreySarnoff]

they are not official -- they exist to encourage something official, and to contribute to that (they represent the views of a dozen or so of the more involved contributors at the time)