Coding Standards Documentation

Coding Standards Index edit
Introduction Overview Documentation	Variables Menus AJAX Calls

All projects need documentation and BOARD18 is no exception.

This page is intended to standardize the inline documentation (comments) that are included in the BOARD18 code.

Some text taken from these coding comments may also appear in the BOARD18 Design Document.

JavaScript Code Files

Most of the JavaScript code that is part of BOARD18 is stored in files in the scripts folder. Usually there is one such file for every BOARD18 page. It is generally named the same as the page except for ending in .js. A few pages have more than one such file associated with them. In that case the script files are numbered.

Each script file should begin with a comment containing the standard copyright notice and any other information about the specific file or its usage.

This is an example of such a file header:

/*
 * The board18Market5.js file contains all the right-click logic.
 * A right click event on the stock chart in the Market page can 
 * cause a context menu to be displayed. Whether this menu is 
 * displayed at all and the selection of items in this menu 
 * are both dependent on the context of the event. 
 *
 * Copyright (c) 2013 Richard E. Price under the The MIT License.
 * A copy of this license can be found in the LICENSE.text file.
 * 
 * All BD18 global variables are contained in one
 * 'master variable' called BD18.  This isolates 
 * them from global variables in other packages.
 */

JavaScript Functions

JavaScript functions for each BOARD18 page are grouped in the script files for each page.

Each such function should be proceeded with an explanation of its purpose.

This is an example of the documentation for such a function.

 
/* The dropToken function places a token at a specified 
 * location on the map board.  It calls the BoardToken
 * constructor function and then updates some global
 * variables to keep track of the new token. Note that
 * this new token has not yet been permanently added to
 * the list of placed tokens in BD18.gm.brdTks. It is 
 * tracked instead in the BD18.tempToken array.
 */
function dropToken(x,y,xI,yI) {

Called PHP Programs

Most of the server side processing for BOARD18 is done in stand alone PHP programs that are executed from the web pages via AJAX calls. They are usually (but not always) stored in separate files. These files are placed in the php folder.

The files that contain these programs should all begin with a block of comments with the following format.

• A paragraph explaining the function of the program.
• A description of all of the input parameters to this program.
• A description of the output produced by this program.

The following is an example of comments that follow this standard.

 
 * gameGet.php is the server side code for the AJAX gameGet call.
 * 
 * It returns most fields for a game from the game table.
 * It also returns a list of the players who are playing the game.
 * 
 * Input is: gameid.
 * 
 * Output is the following stringified JSON data structure. 
 *   {
 *     "stat":"success||"fail"||"noplayers",
 *     "gameid":"nnnn",
 *     "gname":"aaaaaa",
 *     "boxid":"nnnn",
 *     "bname":"bbbbbb",
 *     "version":"vvvvvvv",
 *     "sdate":"yyy-mm-dd hh:mm:ss",
 *     "adate":"yyy-mm-dd hh:mm:ss",
 *     "lastupdater":"llllllll",
 *     "status":"sssss",
 *     "players":
 *     [
 *       {
 *         "playerid":"nnnn",
 *         "login":"pppppp",
 *         "fname":"fffffff",
 *         "lname":"ggggggg"
 *       },
 *       . . . . more players . . . . . 
 *     ]
 *   }
 *

CSS Stylesheets

CSS is used to format BOARD18 pages. Most of this CSS code is placed in CSS stylesheets which are stored in the style folder. They are generally named the same as the page except for ending in .css.

These stylesheets should all begin with a comment containing the standard copyright notice and other information about the stylesheet.

This is an example of such a file header:

/*
 *  Document   : board18Admin
 *  Created on : Oct 17, 2013, 10:52:03 AM
 *  Author     : rich
 *  Description: CSS Document for board18Admin page.
 *
 * Copyright (c) 2013 Richard E. Price under the The MIT License.
 * A copy of this license can be found in the LICENSE.text file.
 */

This page is a stub.

The BOARD18 Project will soon be expanding it.