JavaScript API Reference/Programming Conventions

Comments

Global variables and objects should have comments that explain their purpose, type and possible values:

/**
* Current reservation status. Numeric, possible values are:
* 0 – new reservation;
* 1 – existing reservation modified by the user;
* 2 – existing reservation deleted by the user;
*/
var reservationStatus = 0;

/**
* Holds the currently selected Reservation object.
* The value is set in the setCurrentReservation() function.
*/
var currentReservation = null;


Functions should have comments that explain their purpose, side effects, input parameters, and return values:

/**
* Sets specified reservation status.
* @param {res_id} Reservation ID, used to find the reservation in the list.
* @param {status} New status to be set.
* @return Old status of the reservation.
*/
function setReservationStatus(res_id, status) {
...
}