Naming convention for atoms, refs, etc.?

[Mars0i]

Does anyone want to suggest or promote a naming convention for atoms, refs, and agents, i.e. some of things that you can dereference with @ i.e. deref?

(Also, what about futures, delays, and promises?  I think of these as playing a different sort of role, even though deref works with them, too.)

The Clojure style guide says:

Use *earmuffs* for things intended for rebinding (ie. are dynamic).

;; good
(def ^:dynamic *a* 10)

It could be reasonable to use earmuffs for atoms, etc., too, but I think that "@*my-atom*" is ugly because of the juxtaposed @-sign and asterisk, and in any event I think of rebinding as a different kind of thing from what happens with atoms/refs/agents.

[Mars0i]

&, $, and ! might be good to use as special naming characters for atoms/refs/agents, either as an initial char, a final char, or both, but I'm wondering whether anyone already has a naming convention that they use.

[James Reeves]

Why should they have any sort of naming scheme? Dynamic vars are unusual because their values can change. Atoms and refs remain the same, and even though inside their values mutate, they don't affect the outer var.

- James

--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clo...@googlegroups.com
Note that posts from new members are moderated - please be patient with your first post.
To unsubscribe from this group, send email to
clojure+u...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
---
You received this message because you are subscribed to the Google Groups "Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email to clojure+u...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Timothy Baldridge]

Also, if you have so many atoms in your program that it becomes hard to remember where they are, that would be another source of concern ;-)

--

“One of the main causes of the fall of the Roman Empire was that–lacking zero–they had no way to indicate successful termination of their C programs.”
(Robert Firth)

[Mars0i]

On Saturday, December 5, 2015 at 5:45:22 PM UTC-6, James Reeves wrote:

Why should they have any sort of naming scheme? Dynamic vars are unusual because their values can change. Atoms and refs remain the same, and even though inside their values mutate, they don't affect the outer var.

Good point, James.  They're just regular variables.  Still, their role is very different from that of normal Clojure variables.  I prefer to give them a different kind of name.  But I can understand why others wouldn't.

[Mars0i]

On Saturday, December 5, 2015 at 8:04:34 PM UTC-6, tbc++ wrote:

Also, if you have so many atoms in your program that it becomes hard to remember where they are, that would be another source of concern ;-)

Yeah ....  I'm worried that I'll come back to the code a year later and not remember that the variable contains an atom, and wonder why I'm getting different things out of it.  Though I suppose the at-sign might be a tip-off.

Or suppose I have a recurrent role in several functions or several namespaces or several programs, for which I always use the same name.  Using the same name in different contexts makes the meaning of the variables clear.  Then it turns out that I have to make a new special version of this kind of program, in which I need to store the same kind of data in an atom rather than simply passing it from function to function.  I want to give the variable containing the data the same name ... but I don't, because this variable is different--it contains an atom containing the usual data, rather than the data itself.  (This is actually the situation that prompted the question.  I don't like having to store the data in an atom, but )

[Gregg Reynolds]

Postfix @?  Haven't pondered this before but I like the idea.  Why should perl have all the fun?

On Dec 5, 2015 3:47 PM, "Mars0i" <mars...@logical.net> wrote:

&, $, and ! might be good to use as special naming characters for atoms/refs/agents, either as an initial char, a final char, or both, but I'm wondering whether anyone already has a naming convention that they use.

--

[Gregg Reynolds]

Ps.  Note the nice symmetry between *foo* and @foo@.

[Nicola Mometto]

'foo@ is not a valid symbol name

[Gregg Reynolds]

On Dec 6, 2015 2:45 PM, "Nicola Mometto" <brob...@gmail.com> wrote:
>
> 'foo@ is not a valid symbol name

Oops.  Maybe now is the time to make good on "other characters may be allowed eventually" (from the Reader doc.)  I can't think of a good reason not to allow @ in symbols.  Would it mess anything up?

[Nicola Mometto]

I seriously doubt that's ever going to happen. There's no good reason to do that.

[Glen Mailer]

I saw some sample code that prefixed the atom name with a ! recently, seemed to look sensible to me.

(swap! !state conj :whatever)

And so on.

[Mars0i]

This idea is conceptually elegant, since the marker, !, is the same as the related function suffix. 

I worry that having two bangs with a space between them, as in the swap! example above, is a little bit visually confusing.   Also, I wonder whether placing @ next two another non-alphanumeric character is visually confusing or messy. 

As an experiment, I just started using & as a suffix for variables whose values are atoms.:
(def state& (atom 1))
(swap! state& inc)
@state&

Using only a suffix character means that you don't have a punctuation character next to @, which I prefer. 

(I wouldn't want to use ! as the suffix for variables that are not functions, though.  (swap! state! inc) potentially very confusing.  It's not that someone reading it couldn't figure it out, but if I saw that, I'd have to think for a second, and then keep remembering that state! is not a function.)

It occurred to me that I've seen both & and $ used in some languages to suggest pointer dereferencing, so there's some vague harmony to using one of them as indicators as markers of statefulness.  "Ampersand" sounds vaguely like "atom".  If one wanted to have separate marker characters for atoms, refs, and agents, maybe & is a good choice for atoms.  Not sure it's necessary to have different conventions for these three distinct uses, though.

[Daniel Kersten]

I personally don't like this.

An atom won't suddenly change value without your knowledge because to get its value, you must use @ or deref (which should be a big warning that, yes, this value might change between calls to deref).

Adding sigils, in my opinion, adds to the noise and makes it harder to read. I personally find sigils to be a noisy mistake in other languages (perl, php etc) and in my opinion you can get more benefit through a suitable naming convention such as a -state prefix, eg: foo-state

I think, mainly my dislike for sigils is on variables and not so much on functions as I'm ok with foo? being a predicate and foo! being unsafe in STM. I think that's because they tell you useful meta information about what the function does, but to use a variable, I already have to know what data it's representing in order to call the correct functions on it and annotating it with sigils doesn't help much (unless perhaps you go full blown Hungarian notation, but even that isn't rich enough to adequately describe the nested data structures we use in Clojure - good descriptive variable names are much better at conveying content and purpose).

I guess it may largely just be personal taste, although I would also take the wider community into account: there's a lot of code out there not using this convention - will that become confusing if you rely on symbols to tell you that a variable is an atom?

--

[Colin Yates]

+1.

I haven’t done an extensive study, but I am sure all of my atoms’s stand out from other fns/vars because the name makes it obvious. For example, ‘shopping-cart’ can _only_ sensibly be state which can only be an atom. 

Having said that, if I had mixed refs and atoms then I might consider splitting those, but in general I find it obvious and intuitive when looking through past code which are atoms and which are fns/vars.

Might just be me though :-). 

[Daniel Kersten]

Good point, Colin, about mixed refs and atoms. That might change things a little (although in my years of Clojure, I have never needed to mix them to the point of needing to clarify).
I would still prefer a textually descriptive name over a symbolic prefix or suffix in this case though. At the very least, something like foo-atom or foo-ref would be clear to people not used to the convention, while foo& could mean anything. I think usually one can come up with better descriptions than -atom too.

But... Maybe I'm just a little bit too symbol averse 🤔😏

[Mark Engelberg]

On the contrary, I find that when I have something in my app like a shopping-cart, there are usually two flavors of functions.  On the one hand, there will be helper functions that take an immutable shopping-cart and return a new immutable shopping-cart.  But on the other hand, there will also be a few functions that manipulate the actual stateful atom/ref containing the immutable shopping-cart.

I can see how some sort of convention might be handy to distinguish, at a glance, whether a function takes the immutable or stateful version of shopping-cart by some symbol in the name of the input.

[Colin Yates]

Sure - but if I saw a reference (no pun intended) to ‘shopping-cart’ I would expect that to be stateful. Fns which take something and return something else I tend to name `something->something-else`. In other words, I am unlikely to have a var whose name is a lower-case noun that isn’t state. 

It is interesting to me, now I think about it that I have seen a few syntactical style guides but no semantic style guides for Clojure. This question suggests we need one….

[Mars0i]

Another use case, fwiw:

(def my-atom
  (let [...
         <many lines>
         ...]
    (atom ...)))

A special naming convention for (e.g.) atoms makes it clear that what's below the many lines of let bindings (and maybe comment lines, too) is going to produce an atom; you don't have to read down and find the one line that contains '(atom'.

[Colin Yates]

I know it is dangerous to make sweeping statements, but any solution to “a lot of code obscures meaning therefore do X” is often solving the wrong thing - the real problem is "a lot of code that obscures meaning” :-).

I hope that doesn’t come across as condescending as I fear...

[Daniel Kersten]

I write such code like this:

(defn sdescriptive-name [] <many lines>)

(def my-atom (atom (descriptive-name)))

Where descriptive-name would describe the data shape or purpose.

This way the atom is not obscured behind many lines of code and the data-generation is factored into a testable function with a hopefully self-documenting name.

[Mars0i]

On Thursday, December 10, 2015 at 4:40:49 AM UTC-6, Dan Kersten wrote:

I write such code like this:

(defn sdescriptive-name [] <many lines>)

(def my-atom (atom (descriptive-name)))

Where descriptive-name would describe the data shape or purpose.

This way the atom is not obscured behind many lines of code and the data-generation is factored into a testable function with a hopefully self-documenting name.

On Thu, 10 Dec 2015 at 10:27 Colin Yates <colin...@gmail.com> wrote:

I know it is dangerous to make sweeping statements, but any solution to “a lot of code obscures meaning therefore do X” is often solving the wrong thing - the real problem is "a lot of code that obscures meaning” :-).

I hope that doesn’t come across as condescending as I fear...

How dare you. :-)

No, feedback is always good.

As a rule of thumb, I tend to agree, but there are tradeoffs.  In this case the long string of let bindings are all similar, and are used to create an initial data structure that plays a central role in a simulation.   Different simulations vary only by what's in this data structure.  It's clearest to keep the bindings together in one place, and there's no reason to pollute the top level.

Daniel's solution is a good one.  I had the code set up that way at one point, and may go back to it.

(Normally I store the data structure directly in a top-level variable, which is referenced only once at the beginning of simulation runs, and update the structure in a purely functional way.   Because of interaction with another program in my current project, I now have to maintain the structure in a state variable that changes, so I've added the atom wrapper.  Same kind of data structure as in the purely functional versions, though.)