Coding Standards Documentation - Revision history

Rich: removed stub

2020-07-24T19:05:55Z

removed stub

← Older revision		Revision as of 19:05, 24 July 2020
Line 161:		Line 161:
	*/		*/
	</pre>		</pre>

	~~{{Stub}}~~

	[[Category:Standards]]		[[Category:Standards]]

Rich: /* BOARD18 Page Files */ initial contents

2020-07-23T15:17:22Z

BOARD18 Page Files: initial contents

← Older revision		Revision as of 15:17, 23 July 2020
Line 8:		Line 8:

	== BOARD18 Page Files ==		== 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:
			<pre>
			<?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>
			</pre>

	== JavaScript Code Files ==		== JavaScript Code Files ==

Rich: Added reference to design document

2020-07-23T12:41:13Z

Added reference to design document

← Older revision		Revision as of 12:41, 23 July 2020
Line 1:		Line 1:
	{{Coding Standards Index}}		{{Coding Standards Index}}
	All projects need documentation and BOARD18 is no exception. ~~<br>~~		All projects need documentation and BOARD18 is no exception.
	This page is intended to standardize the inline documentation (comments) that is included in the code.
			This page is intended to standardize the inline documentation (comments) that are included in the BOARD18 code.

			<span style="color: Fuchsia">Some text taken from these coding comments may also appear in the </span>
			[[Design_Document_Introduction\|BOARD18 Design Document]].

	== BOARD18 Page Files ==		== BOARD18 Page Files ==
Line 97:		Line 101:
	== CSS Stylesheets ==		== CSS Stylesheets ==
	CSS is used to format BOARD18 pages. Most of this CSS code is placed in CSS stylesheets which		CSS is used to format BOARD18 pages. Most of this CSS code is placed in CSS stylesheets which
	are stored in the '''style''' folder.		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		These stylesheets should all begin with a comment containing the standard copyright notice and

Rich: Added some new sections. Still needs more work!

2020-07-23T12:25:08Z

Added some new sections. Still needs more work!

← Older revision		Revision as of 12:25, 23 July 2020
Line 1:		Line 1:
	{{Coding Standards Index}}		{{Coding Standards Index}}
	All projects need documentation and BOARD18 is no exception~~. <br>I have been trying to keep up with this need while developing BOARD18~~.<br>		All projects need documentation and BOARD18 is no exception. <br>
	This page is intended to standardize the documentation (comments) that is ~~actually~~ in the code.		This page is intended to standardize the inline documentation (comments) that is included in the code.

			== BOARD18 Page Files ==

			== 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:
			<pre>
			/*
			* 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.
			*/
			</pre>

			===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.
			<pre>
			/* 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) {
			</pre>

	==Called PHP Programs==		==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.~~<br>~~		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.		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 paragraph explaining the function of the program.
Line 45:		Line 94:
	</pre>		</pre>

	~~==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~~.		== 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.

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

	This is an example of ~~the documentation for~~ such a ~~function.~~		This is an example of such a file header:
	<pre>		<pre>
	/* ~~The dropToken function places a token at a specified~~		/*
	* ~~location~~ on ~~the map board. It calls the BoardToken~~		* Document : board18Admin
	* ~~constructor function and then updates some global~~		* Created on : Oct 17, 2013, 10:52:03 AM
	* ~~variables to keep track of the new token~~. ~~Note that~~		* Author : rich
	* ~~this new token has not yet been permanently added to~~		* Description: CSS Document for board18Admin page.
	* the ~~list of placed tokens in BD18~~.~~gm.brdTks. It is~~		*
	* ~~tracked instead~~ in the ~~BD18~~.~~tempToken array~~.		* Copyright (c) 2013 Richard E. Price under the The MIT License.
			* A copy of this license can be found in the LICENSE.text file.
	*/		*/
	~~function dropToken(x,y,xI,yI) {~~
	</pre>		</pre>


	{{Stub}}		{{Stub}}

	[[Category:Standards]]		[[Category:Standards]]

Rich: /* JavaScript Functions */ initial contents

2017-10-14T18:35:03Z

JavaScript Functions: initial contents

← Older revision		Revision as of 18:35, 14 October 2017
Line 46:		Line 46:

	==JavaScript Functions==		==JavaScript Functions==
	to ~~be provided~~.		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.
			<pre>
			/* 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) {
			</pre>


	{{Stub}}		{{Stub}}

	[[Category:Standards]]		[[Category:Standards]]

Rich: /* Called Programs */ added example

2017-10-14T18:23:32Z

Called Programs: added example

← Older revision		Revision as of 18:23, 14 October 2017
Line 3:		Line 3:
	This page is intended to standardize the documentation (comments) that is actually in the code.		This page is intended to standardize the documentation (comments) that is actually in the code.

	==Called Programs==		==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.<br>		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.<br>
	The files that contain these programs should all begin with a block of comments with the following format.		The files that contain these programs should all begin with a block of comments with the following format.
Line 9:		Line 9:
	* A description of all of the input parameters to this program.		* A description of all of the input parameters to this program.
	* A description of the output produced by this program.		* A description of the output produced by this program.

			The following is an example of comments that follow this standard.
			<pre>
			* 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 . . . . .
			* ]
			* }
			*
			</pre>

			==JavaScript Functions==
			to be provided.

	{{Stub}}		{{Stub}}

	[[Category:Standards]]		[[Category:Standards]]

Rich: Created page with "{{Coding Standards Index}} All projects need documentation and BOARD18 is no exception.
I have been trying to keep up with this need while developing BOARD18.
This pag..."

2013-12-15T17:54:09Z

Created page with "{{Coding Standards Index}} All projects need documentation and BOARD18 is no exception. I have been trying to keep up with this need while developing BOARD18. This pag..."

New page

{{Coding Standards Index}}
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 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.

{{Stub}}

[[Category:Standards]]