JavaScript

The Basics

First and foremost, we make an attempt to adhere to the WordPress JS coding standards.

Top ↑

Code style

All javascript should be well documented. Functions, namespaces should adhere to the jsdoc 3 standard, available here.

Inside functions declare additional comments with the // syntax.

Top ↑

Variable declaration

While not a fully ratified standard, nor heavily enforced, comma-separated variable declarations should be discouraged.

Icky:

var v, x, y;

var $this = $(this),
  $that = $(that),
  i = 0;

Preferred:

var v;
var x;
var y;

var $this = $( this );
var $that = $( that );
var i     = 0;

Top ↑

HERE’S @BORKWEB’S REASONING FOR SEPARATE VAR STATEMENTS

Personally, I’d prefer to separate the function declarations from the variable declaration chain. One of the following would allow proper docblocks without chunking up the declarations and avoid funky-looking nesting:

var dateToYmd = function( date ) {
  // ...
};

or

function dateToYmd( date ) {
  // ...
}

I still am not a fan of chained declaration in general. Here’s my reasoning:

1. Chained declarations deter comments being added for individual variables and sorta hurt readability: var /** * This variable does something interesting * * @private **/ variableX = 1, /** * This variable does something else entirely * * @private **/ variableY = 2;
2. Chained declaration statements make them harder to move around and cause needless churn in diffs and increase the possibility of merge conflicts: var x = 1, z = 3, y = 2; // changing it to the following would result in 2 changed lines: var x = 1, y = 2, z = 3; vs the following: var x = 1; var z = 3; var y = 2; // change it to the following would result in 1 changed line: var x = 1; var y = 2; var z = 3;
3. Variable alignment of chained declarations is unpleasing to my brain (I know I could solve this by setting my tabs to 4…but that’s not going to happen): // compare this var x = 1, y = 2, z = 3; // to: var x = 1; var y = 2; var z = 3;
4. Our unminified code should be all about readability and not saving bytes. Good minifiers turn multiple var statements into comma-separated ones.
5. On the topic of saving bytes…In the event that the non-minified version of the JS file is served up to the user…two var statements gzip better than a single var with a comma. (via Isaac of NPM – source)

Top ↑

jQuery var names

Variables that point to a jQuery object should have their name prefixed with a $ sign, per the examples above.

Utility functions, state, tests, and options for the main plugins should be stored in tribe-events.js and tribe-events-pro.js.

If functions or portions of functionality move between plugins, make sure all associated js code moves to that new area with them.