Project:Sandbox

קהש

 Pending Changes
 * for Requirements and Examples:

if a standard tag for auto-documentation tools exists for a given language/file format, then use that tag instead of the [SCM PATH] tag

Requirements

 * 1) Each file shall include the following tags and information at the beginning of the file, as commented out text:
 * 2) [SCM PATH] 
 * 3) [PURPOSE] 
 * 4) Each file shall include ad-hoc comments throughout the file that describe the following:
 * 5) classes
 * 6) methods/functions
 * 7) sections
 * 8) non-standard things
 * 9) non-obvious things
 * 10) For any inactive (ie “commented out”) lines or sections of code, there shall be a comment preceding it, explaining why the code exists but is currently commented out. This explanatory comment should use one of the following tags, as appropriate:
 * 11) [DEBUG]
 * 12) [INACTIVE -  ]

Examples
The following example is for Requirement 1:

The following example is for Requirement 3:

// [INACTIVE - see OTRS Ticket#1000123 for explanation] /* ...       // [DEBUG] //mail("Steven.Zollo@team.adam.com.au", "Planchange Error", $msg, "From: Soap Functions \r\n" . "Reply-To: accounts@adam.com.au\r\n" . "X-Mailer:PHP/"); ... */

Applies To

 * ALL FILES:
 * code
 * script
 * configuration

Action When

 * 1) You create a new file.
 * 2) You do any work on an existing file.
 * 3) You are specifically tasked to work on in-code documentation for a given file.

Policies, Procedures & Guidelines :: Inside-Code Documentation