So I have a somewhat obsessive need to use full words instead of abbreviations when I code. I think it really helps public library code to be readable and self-documenting. I was thinking today that I would have fun going through the JuliaLang/julia and replacing all abbreviations with full words. Of course, I wouldn’t change any part of the public API, just internal code. But I didn’t want to waste my time if no one would accept a PR, so I wanted to explore the idea here first?
4 Likes
Please don’t.
3 Likes
Why not?
1 Like
in my personal repositories made publicly available, I prefer abbreviations to fit as much code on my screen as possible, so that I can get a better overview of it
also, since nobody paid me or sponsored me, I don’t think I owe the world an explanation
for big repositories like Julia, I imagine it would take attention away from important issues
It makes the code longer, therefore more likely to not fit on a screen and harder to read. It’s harder to pattern match long strings to figure out which name you are using. In general, it makes the code hard to read.
It’s not really solving a real problem. The real problem is the readability of the code, abbreviations has nothing to do with it. Knowing some names used in the local context is the simplest task when reading code. There’s no way for the names to explain all you need to know about the variable anyway so make them easy to recognize and remember and don’t play with the name more than that.
You are certainly welcome to add comments, that will help readability. If there’s short names that looks confusing like sth else, feel free to fix those too. Replacing all abbreviations is just doing it for the sake of doing it, it serves no real purpose.
10 Likes
I don’t think I owe the world an explanation
Self-important attitudes like this I think are incredibly destructive to open-source communities
likely to not fit on a screen
Can’t you just zoom out?
1 Like
No, the screen vs the font size is not the issue. In fact, the screen (window) size / font size should be fixed. Human eye/brain does not have infinite resolution. If you zoom out, you have to get closer to see and the total number of text you can glance at once does not change at all. (If it changes, it just mean that you font size is too big to begin with)
I also disagree with this. It’s perfectly fine to only care about what one need oneself. It’s the fact that different people interested in different aspects that helps a project improve. Not everyone should care about everything. I definately don’t. In fact, I rarely contribute to any project on any aspect that I don’t use.
I don’t think this is an argument that’s relevant very much here though. It merely means that @chakravala do not want to, doesn’t have to and should not submit such a PR and neither will I. It’s not an argument against you doing it. (Again, my other arguments still apply)
5 Likes
What is self-important about it? I don’t have infinite time and energy available
I agree it’s probably pointless to point out, but I’m just explaining why my code is the way it is
2 Likes
Ok, well, I guess that’s a hard no then. Glad I asked first lol
FWIW:
Names should be descriptive; avoid abbreviation.
Give as descriptive a name as possible, within reason. Do not worry about saving horizontal space as it is far more important to make your code immediately understandable by a new reader. Do not use abbreviations that are ambiguous or unfamiliar to readers outside your project, and do not abbreviate by deleting letters within a word. Abbreviations that would be familiar to someone outside your project with relevant domain knowledge are OK. As a rule of thumb, an abbreviation is probably OK if it’s listed in Wikipedia.
https://google.github.io/styleguide/cppguide.html#General_Naming_Rules
2 Likes
Well at least Google agrees with me?
From my reading of the conversation, Google’s style guide falls somewhere in between your proposal and @yuyichao’s rejection of your proposal. The recommendation is not to remove all abbreviations. However, abbreviations that make sense only in a local (i.e., file-level) context and not a domain-wide (e.g., linear algebra) context arguably make the code harder to read.
The Linux Kernel also does not accept patches in which only the names of things are changed
although, they might have changed their policy with their new code of conduct
1 Like
The julia source seems heavily abbreviated to me, with most internal names being just one or two letters. I’m pretty sure Google wouldn’t approve.
No all abbreviations are bad, a lot depends on context. In simple cases, when they are perfectly understandable, abbreviations should be fine.
Even if some existing code should benefit from expansion, it may be better to just leave it alone and wait for some substantial reason that requires touching that code, and then improve on style if necessary. Someone needs to review these PRs, and pure coding style improvements (which are often in the eye of the beholder) may not be an efficient use of their time.
Also, if there are no explicit violations of a specific coding style, it may be fine to assume that the person who wrote some code and got it accepted as a PR is an experienced programmer who knew what he/she was doing. You may do some things differently, but that alone might not be a good reason for a PR.
Finally, I think it is great if you have time for contributing to Base and the standard libraries with an eye to small details. There are many minor open issues that could benefit from your work.
9 Likes
Related topic
It would be hard to change the style completely for a large project like Julia. If we do it partially then it becomes too inconsistent to be useful. Also, existing contributors will probably finding it unpleasant (as seen above).
1 Like
When we take Google as an authority, we should also consider the fact that Go has different style for variable names:
Variable names in Go should be short rather than long. This is especially true for local variables with limited scope. Prefer
ctolineCount. PreferitosliceIndex.The basic rule: the further from its declaration that a name is used, the more descriptive the name must be. For a method receiver, one or two letters is sufficient. Common variables such as loop indices and readers can be a single letter (
i,r). More unusual things and global variables need more descriptive names.
9 Likes
Well, I specifically had to ask what, e.g., ptls stood for. A few longer words would definitely help
Pointer to thread local storage. There’s no way you’ll put this full name in.
It’s not user facing and is not particularly well documented in the code and you are very welcome to add those comments around where it’s declaration in the header tls.h. A long version of the doc can be found in the definition in threading.c.
2 Likes