Generic property names confuse the beginner

DocumentJS
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 a keyword or with other properties with the same name.

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?

I haven’t see any responses to this post; not sure if it was understood, so here’s another example, from the Video Player recipe:

can.Component.extend({
  tag: "video-player",
  view: `
    <video controls
      on:play="play()"
      on:pause="pause()">
      <source src="{{src}}"/>
    </video>
    <div>
      <button>
        {{#if(playing)}} Pause {{else}} Play {{/if}}
      </button>
    </div>
  `,
  ViewModel: {
    src: "string",
    playing: "boolean",

The variable used to initialize src= is named src, resulting in the code <source src="{{src}}"/>. Naming this variable vidsrc instead would improve comprehension.

2

Thanks for the feedback!

On pages where you see names that can be improved, please feel free to use the “Edit on GitHub” button towards the top of the page to improve the docs.

Our style guide mostly points to jQuery’s style guide, which encourages using full words for variable/property names. In that last example you posted, I think videoSource or videoSrc would be more clear.

3

FYI, I’ve lodged my first “distinctive identifier names” PR: https://github.com/canjs/canjs/pull/4234.

1 Like