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.

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.

BOARD18 Page Files

BOARD18 is implemented as a number of separate pages. Each page is stored in its own file in the root folder of the application.

With 2 exceptions, each page file is named board18xxxx.php where xxxx is the unique page name. For example the Main page is named board18Main.php.

The page file has 3 sections. First a PHP section then a comment section then a HTML section. As part of the HTML section, a script containing JavaScript code will often occur.

This is a sample of the top part of a BOARD18 page file:

<?php
require_once('php/auth.php');
?>
<!doctype html>
<!--
The board18Main.php page displays a list of the logged in player's active
games. The player can select any of the listed games to start a game 
session in that game or to link to the board18Misc page where miscellaneous
service actions can be performed for that game. He can also select
a link to the board18New page if he wishes to start a new game.

Copyright (c) 2013 Richard E. Price under the The MIT License.
A copy of this license can be found in the LICENSE.text file.
-->
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>BOARD18 - Remote Play Tool For 18xx Style Games</title>
    <link rel="shortcut icon" href="images/favicon.ico" >
    <link rel="stylesheet" href="style/board18com.css" />
    <link rel="stylesheet" href="style/board18Main.css" />
    <script type="text/javascript" src="scripts/jquery.js">
    </script> 
    <script type="text/javascript" src="scripts/board18com.js">
    </script>
    <script type="text/javascript" src="scripts/board18Main.js">
    </script>
    <script type="text/javascript" >
      $(function() {
        $.post('php/myGameList.php', listReturn);
      }); // end ready
    </script>
  </head>

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.
 */