Coding Standards Documentation

From BOARD18 Project WIKI
Jump to navigation Jump to search
Coding Standards Index edit

All projects need documentation and BOARD18 is no exception.
I have been trying to keep up with this need while developing BOARD18.
This page is intended to standardize the documentation (comments) that is actually in the code.

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.
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 . . . . . 
 *     ]
 *   }

JavaScript Functions

JavaScript functions for each BOARD18 page are grouped in one or more 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 It is 
 * tracked instead in the BD18.tempToken array.
function dropToken(x,y,xI,yI) {

This page is a stub.
The BOARD18 Project will soon be expanding it.