In today’s Tinderbox Meetup, Peter Wasilko in an aside made a suggestion I think to be brilliant.
It’s often useful to distinguish Tinderbox prototypes and templates from other notes. Long ago, I myself started the name with an asterisk *Task. This was a lousy idea and I gave it up years ago, but it lives on.
Peter mentioned that his convention is as follows:
It is lovely, but sometimes I want to use a $Name that includes A(n) or The because that’s part of the title of the thing I’m writing about.
My own convention is to always put prototypes into a Prototypes container, prefacing them with p, such as pBook, and templates into a Templates container, prefacing them with t such as tBookNote. This avoids clashes with the names of real things.
Without an intentional +1, my approach follows that of @PaulWalters. I too like the eloquence of the style described but, pragmatically have been caught out when accidentally using prototype titles as titles to non-prototype notes.
An edge case here is that Tinderbox is permissive as to where/when we create prototypes. The emergent method is to simply make an exemplar note a prototype and use wherever.
Deeper use of the app seems to push most people to abstracting from the above into prototypes stored in the app-default /Prototypes container. Even so ‘Event’ is more likely to achieve a hard to spot/diagnose name collision than ‘*Event’, ‘_Event’, ‘pEvent’ etc.
I think the latter becomes more of an issue if using action and/or export code at more than trivial level. Of course, that isn’t all users or all communities of practice, so we have space to embrace different method.
For teaching/informing others however, I’d always use prefixes (or similar flagging of special purpose). Why? Because it avoids learners tripping over problems they likely don’t/won’t understand at first encounter. Once one is more proficient with the app, then is the time to explore naming conventions closer to personal taste and community of practice. In this context, aTbRef’s ‘rules’ (habits?) for naming things, and which I try to conform to where possible in forum posts is described here: aTbRef's naming conventions. If they act as provocation to the reader to use a more elegant solution, I’ll take that as a win.
Where the two approaches align is in loop variables where I use ‘A’ or ‘An’ plus what is being iterated: each("AnEvent"){}, or .each("APerson"){}. The latter makes it more explicit in-loop what is being dealt with. Experienced coders can go with names like x, as they hold in mind the abstraction of for what x stands proxy. But, shared with non-coders that can be unhelpfully obfuscatory, not least because it rests on a not of unstated assumptions about conventions in code (as absorbed/acquired during formal coding education).
So whilst I like the linguistic elegance of the suggested method, I’ve doubts—from practical experience—as to the practicality. But we’re a broad church here and I’d not want the last to imply judgment of others. There is room for all, another nice aspect of this app and community.
I agree that the convention ought not to preclude note titles like A Separate Peace and The Roman Emperor which are neither prototypes not templates. And, if you want an agent or an action to consider whether a note is a prototype, $IsPrototype is definitive.
Still, I do think A Task in the Prototypes folder looks better than pTask, and newcomers might find it more welcoming.
Cute as this is, it’s giving me horrific flashbacks to writing Lingo for Director, which had adopted ‘natural language’ for programming simplicity, but as demands on the language increased lead to bafflingly complex statements like
Tell the the sprite 5 of the the window
and that moment when the simplicity creates an overwhelming complexity.
And while A/The are very good conceptual models, there may be an extra layer of confusion for people whose first language does not adopt articles the way English does; I remember picking up Programming Perl in Cantonese at a friends’ house and suddenly being hit by how much about programming, conceptually, syntactically and grammatically, builds on familiarity with English. Korean - for example - doesn’t even bother with articles, occasionally hinting at them as word-ending additions as particles. And hoping not to come across as someone with cursory linguistic experience around authoritarian regimes, Russian doesn’t bother with them either; though whether this affects sales under the hypertext software sanctions is another matter.
I agree. There should be a balance between the “visual aesthetic” and the “programming/efficiency aesthetic.” In this context, I believe the concise programming/efficiency aesthetic would win out in the long term, as there is beauty in the consistency and efficiency that it affords. I agree with @eastgate, however, that the benefits of this position may not be fully appreciated or understood by the novice or casual user.
Sorry to jump in on an old topic but is it possible to combine somewhat. I didn’t take to the “p” prefix for prototypes and use aTask, anEvent, aReference etc just because it seems more natural. Leaving out the space makes it obvious to me that it’s a prefix and also leaves the possibility of note names like “a task”
Yes, the point is to find one’s own rhythm with such naming. One size doesn’t fit all. Here in the forum, you will see some apparent common styles but that is mainly out of considerations to the general reader. Consistency aid comprehension and it’s little work to take a code sample and rename things like prototypes to make it your own. Actually, for the learner, it’s quite good for moving one beyond copy pasting ‘magic’ samples. Knowing where things are named/stored, the interaction between attributes and action/export code, and what can or can’t be renamed without secondary edits elsewhere, are all valuable knowledge for longer term use of Tinderbox. As a toolbox rather than a process, the app repays some understanding of whats in the box: just because the hammer or the 2x3 lego brick are on the top of the pile we don’t have to use them for everything.
As aTbRef’s author, I try to use the same conventions in helping here in the forum as in the resource. Indeed, I described aTbRef's naming conventions in some detail here. No one has to use them in their own work. The aim is to aim understanding/learing, so in example:
$MyList = collect(children, $Price);
this aims to show the user that the output of the collect() operator is a list. In our own work we can call it what we like.
Conversely, with some user’s problems brought here, the first task is to parse their personal naming methods. Indeed, sometimes it is that naming that obscures otherwise obvious errors, e.g. where the data type assumed to be in use is not so with inevitable confusion arising.
Looping back to the start, find a naming method in your documents that suits you. Feel free to translate naming used on other’s code into your style—it will still work.
