pointer_to_local_storage seems fine?
I put my vote for a_variable_representing_pointer_to_thread_local_storage 
2 Likes
TLS is a domain-standard abbreviation. ptls is not, however. If weāre nit picking on the names, I would suggest ptr_tls.
I wouldnāt suggest that Google has any authority over Julia coding style (nor do I speak for Google in any capacity). I would argue, however, that it would be beneficial for the Julia core developers and the broader community to converge on style guidelines and enforce them with some consistency. Existing style guidelines from an array of communities could be useful to draw from. As a Google employee I have some experience interpreting the Google style guides, so theyāre the first that come to mind as an example.
In the JuMP style guide weāve stated its motivations as:
- conveying best practices for writing readable and maintainable code
- reducing the amount of time spent on bike-shedding by establishing basic naming and formatting conventions
- lowering the barrier for new contributors by codifying the existing practices (e.g., you can be more confident your code will pass review if you follow the style guide)
Weāve had a JuMP style guide for about a year, and Iād say itās been relatively successful at meeting these goals. It saves a lot of time when reviewing PRs if I can point to a link in the style guide. People are generally happy to follow conventions if youāve written them down clearly.
6 Likes
On whether itās worth it to accept PRs that address only style issues, it depends. For JuMP I would be happy to receive PRs that are obvious improvements, e.g., making the code more consistent with JuMPās own style guide by fixing formatting. This reduces the amount of technical debt in JuMP. I would be less likely to approve a PR that makes changes that are orthogonal to the style guide or feel like bike shedding. (If you have a great idea to make code more readable, make a PR on the style guide first before taking aim at the code base.)
1 Like
In my repositories, if a third party wants to have a stylistic change (without any other contribution other than stylistic changes for internal names), then that third party ought to pay $$ for the privilege of dictating style. It is specifically my stylistic choice to use compact variable names, even though I dont explicitly state so in a dedicated style declaration. If it is an external variable name part of the API, then it is always open for discussion, of course.
In my opinion, an external party should not be able to have a say in purely internal stylistic choices of another repository unless they are seriously invested in that project financially.
Sounds like this would be the most reasonable strategy in base too. That is an opinionated style guide just for base (donāt worry about developing a universal style for all Julia packages that will undoubtedly cause endless debates). That way when we donāt agree on something like this there is at least a way for us to understand each other. It would be a shame to miss out on generous offers by people willing to clean code, like @bramtayl.
1 Like
Though maybe well intended, it can be as much as an offer as a distraction/disruption. Putting such objective matters in a guideline in a tight manner doesnāt make them less objective, it just shift where the pointless discussion / bike shedding happens. It could even be used as excuses to apply to cases in a way where it clearly shouldnāt.
Thereās certainly an range of abbreviation / degree of abbreviation that are acceptable, even when considering any coding standarnds mentioned here. I have no problem for any PR making actual useful code changes that falls within either side of the spectrum so you can use longer variable names in your new code all you want as long as it doesnāt get ridiculous. However, for a pure renaming changes, especially for base, even without considering the general distraction and disruption of submitting large NFC (and pure renaming) PRs, you donāt even know what domain specific abbreviations are acceptable.
6 Likes
Itās been proven once again that naming things is one of the two hard things in computer science.
Come to think of it, the purpose of having meaningful or verbose names is to make sure that new developers can understand what it does without a lot of cognitive stress. The stress could come from two sources: 1) abbreviations that the new developer do not understand, and 2) the verbosity that makes the code difficult to read.
Some thoughts:
-
Indexing variables are quite easily absorbed even though they are short e.g.
iandjversusstarting_indexandending_index. Cognitive stress is higher when there are multiple index variables that are used in more than several places. -
Thereās no need to make verbose names when passing things around quickly.
-
When domain-specific names like
tlsare used, additional comments could be added either inline, above the function definition, or at the top of the file. In this case, the exported function itself is already self documenting. -
Additional documentation like a developerās manual could be created to explain these abbreviations and coding convention to new developers.
4 Likes
As a person with very programming background who can now write scripts and read some code, I feel Iāll benefit much more from better documentation and comments, than from clearer names. Those can also help, of course, but to me both ptls or point_to_local_storage are fairly meaningless and Iāll rather have a brief explanation of what that is and what it does.
5 Likes
I do like the idea of ptr_tls, but now Iām wondering why the p is there in the first place. Usually the fact that a variable is a pointer is not explicitly mentioned in the variable name
I believe that is common in C-based languages: one might have a variable called x and a pointer to it xp (or px).
1 Like
Let me take a step back and try to understand the problem in its full context.
A program is not just a text - its a formal description of sometimes non-trivial concepts.
Functions, classes, objects, variables may denote quite complex constructions.
Sometimes their meaning may be described in a few words - sometimes not.
More than that, the code which is composed of those elements - is also a construction,
which may not be reduced to just collection of its building elements.
Therefore beside of the question of describing the meaning of the elements one should also consider how to express the meaning of this construction.
In some sense a code is similar to mathematical expressions and formulas used in different technical fields. It took centuries to define formal mathematical language, which is rather abbreviated - and not by coincidence.
Informational complexity of code may be quite comparable to scientific or engineering texts. And in both cases a reader is required to create a map of meanings from the basic concepts in its head before the whole text becomes comprehensible.
Once such map is built, abbreviations of basic element (like in formulas) make it much easier to grasp more complex constructs and follow after ideas.
We should learn to distinguish between accidental and fundamenta complexity of the code (or text), to acknowledge the later and try to minimize the former - not always a simple task.
As we deal with hierarchies of meanings, on some levels properly structured code may be expressed by textually self-defined names to tell a local story without obscuring the bigger picture.
But this is not always the case.
Sometimes to follow a complicated logic of certain algorithms, we prefer to simplify the notation for the building elements, and do expect reader becoming comfortable with the notations before focusing on the higher level of logic.
I suggest those consideration as a guiding principles when selecting the names.
Doubtfully any simple rule can solve this problem once and for all, as the naming is an inseparable part of SW design.
Sometimes ugly names may indicate a need of refactoring.
To summarize, the naming is not a trivial problem, and its not just about the taste.
Unlike an engineering text, created with the only purpose to be comprehended by a person, a program must satisfy yet another, generally not related purpose - to define the algorithm under strict constraints of a given programming language / framework.
No wonder the art of bringing all this together is challenging
3 Likes