Generic property names confuse the beginner


#1

This may seem trivial, but I keep getting confused by passages in the documentation where properties are named with the generic term for the property they represent. Here are some examples:

  1. At https://canjs.github.io/next/doc/guides/atm.html#Mockoutswitchingbetweenpages, the property which controls the state of the ATM is named state:

    <p>Invalid state - {{state}}</p>

  2. At https://canjs.github.io/next/doc/guides/recipes/tinder-carousel.html#Dragandmovetheprofiletotheleftandright, the variable representing the element with class current is named current:

    <div class='current' style="left: {{howFarWeHaveMoved}}px">

    var current = el.querySelector(".current");
    var startingX;
    this.listenTo(current, "pointerdown", (event) => {

  3. At https://canjs.github.io/next/doc/guides/recipes/canvas-clock.html#Drawtheminuteandhourhand, the word time is used as:

    a. The View element used to show the time in the stache, digital, and analog clocks:

    view: '<p>{{time}}</p>
    <digital-clock time:from="time"/>
    <analog-clock time:from="time"/>'

    b. The ViewModel elements used to format the time for the above two Views:

    ViewModel: {
    time: Date,
    hh() {

    ViewModel: {
    time: {Default: Date, Type: Date},
    init() {

    c. The value returned by the listener to the time element’s ViewModel:

    this.listenTo("time", (ev, time) => {

I suppose this does not trouble seasoned programmers who read code by context more than content, but it confuses me.* At least in the Guides I wish there were names which make it obvious they are names only, so I don’t confuse a property with what it represents or other properties.

Here are some possible substitutions for the above examples:

1.<p>Invalid state - {{ATMstate}}</p>

2. var currentEl = el.querySelector(".current");
var startingX;
this.listenTo(currentEl, "pointerdown", (event) => {

3a.
view: '<p>{{nowTime}}</p>
<digital-clock digiTime:from="nowTime"/>
<analog-clock anaTime:from="nowTime"/>'

3b.
ViewModel: {
digiTime: Date,
hh() {

ViewModel: {
nowTime: {Default: Date, Type: Date},
init() {

3c.
this.listenTo("anaTime", (ev, timeLsn) => {

The above names could probably be better; I find them less confusing because they are distinct both from one another and the items (state, class current, time) they represent. Thanks for reading!


*Imagine that, knowing little English, you are sent to the library for a book named Title, written by Author. Certainly this book could exist, and if you surmount the challenge find it you get a free jump-start with your language skills. But what if you don’t make it past the laughing librarians?:grinning:
See also: Who’s On First?