Choosing good names is said to be one of the most difficult things to so in programming.
I'm looking for some advice here.
Let's say I want to talk about an onion in a Racket program. It's somewhat obvious to call it
onion
But onions are data structures, specifically, a struct:
(struct onion (layer pungency))
Now this gives us two uses for 'onion'. It's a structure, and a constructor, and a constructee. In Typed Racket it will likely be a type as well.
Clearly. I need a naming convention to distinguish the multiple meanings.
Has anyone figured out a natural way to name such things?
And what notation should one use in comments to show one is talking about the things called onion in the program rather than just referring to natural-world root vegetables?
HtDP approximately uses “the onion constructor” “the onion structure type” and “an instance of onion” (or longer “an instance of the onion structure type”).
I found myself wanting to give instances the same name as the struct often enough that I created my own (very unofficial) style to distinguish between structs and instances. I suffix ^ to struct names. So I would do:
(struct onion^ (layer pungency)) ; struct is named onion^
(define onion (onion^ 3 'strong)) ; instance is named onion
(println (onion^-pungency onion)) ; both can be used together
It works well for me.
I just write onion in the comments. The surrounding context of the code and the comments generally makes it pretty clear what I mean. If I confuse myself, I've probably picked a bad name for the variable, so I rename it.
onion for the struct name and the-onion or an-onion for an instance name.
Typed Racket style Onion for the struct name and then just onion for an instance.
I don't love either. But if I solo bikeshed on stuff like this for too long, I try to slap myself.
Often I do 1, onion struct, and when the local context is small/obvious, I'll name an instance variable o or even v. (To me, (define (peel-the-onion o) ___) is clear enough. YMMV.)
Aside from style, it's important to realize that Racket will happily let you name the struct onion, and shadow that with a variable named onion. If you think you've locally defined an onion variable, but you didn't, you won't get an undefined variable error using onion. But eventually at runtime your code will misbehave thinking it's using a struct instance value, but instead gets a constructor procedure value. Depending on proximity, this can be tricky to figure out and fix. Ask me sometime.
So there's a good reason to pick different names, beyond style.
On a non-trivial project with multiple people, I might try to get consensus on something like Onion and onion, or whatever the team prefers.
Even (define (peel o) ___) in onion.rkt with (provide (contract-out [peel (-> onion? ___)])) is reasonable for me, but the rest of the comments on bikeshedding are well-said. The closest to convention I've seen is the-onion/an-onion.
