View source for Coding Standards and Practices

{{eras|real}}
==Introduction==
One of the most important aspects of [http://en.wikipedia.org/wiki/Computer_programming coding] [http://en.wikipedia.org/wiki/Website websites] for use within the [[Dark Brotherhood]] is the ability of future generations of members to be able to successfully use and modify the [http://en.wikipedia.org/wiki/Source_code code] to fit their needs. Unfortunately, many [[http://en.wikipedia.org/wiki/Programmer coders] do not leave clean and well-documented code, leaving it nearly impossible to navigate what is left behind. As a part of the effort to continuously improve the code used by the Brotherhood, this document has been developed. This document outlines the best practices and naming conventions that are to be used in all Dark Jedi Brotherhood websites.

The purpose of this document is to assist beginning and experienced developers in the creation of efficient pages. While a wealth of information can be found on the [http://en.wikipedia.org/wiki/Internet Internet], many tips and code samples simply attempt to answer a question or solve a task at hand. A developer must take that information and determine not only how the answer works on the site, but also take into consideration how a technique scale with the rest of the project. By reviewing the best practices mentioned in this document, applications can be made more efficient. It should be noted that this document makes generalizations. Certain practices may need to be ignored depending on the specific needs of a website.


== Code Documentation ==
Documentation is core to the maintainability of code.  Many developers think on very different wavelengths and even a single developer thinks in different ways from year to year.  Documentation is the key to understanding.  Documentation is done in a number of ways and should be done for all code developed for the Brotherhood:

* All variables, functions, and files should be named in such a way that there name is indicative of their usage or contents.
* All scripts should contain a comment for each function including:
** A description
** Explanation of passed in variables
** Description of what is being returned
* Any block or section of code that is doing anything even remotely complex should have an associated inline comment with it. This comment should be short, to the point, and not take up a ton of space.




== Peer Review ==
Prior to launch of the script, another members of the [[Seneschal|SCL]] staff (hopefully your superior) should review your code


== Development Site and Testing ==
All members of the SCL staff and coding team should use the development site for all edits to DB pages and scripts.  Pages should be thoroughly tested on the Development site using the development database and [[Dossier|dossiers]]. Once those pages are tested and reviewed, they may be copied to the live server.


==Code Layout – Tabs and White Space==
Indentations should be a standard width of four spaces. Please note that this does not actually mean you hit space four times; rather, your editor should be set up so that a tab size is four spaces wide. This is normally the default setting. Indentations should be made under any overarching or containing tag. This means that a non-font tag that contains a block of code should have the code it contains indented.  The closing tag should match the original indentation of the opening tag.


== Technology Specific Standards ==
* [[HTML Coding Standards]]
* [[CSS Coding Standards]]
* [[JavaScript Coding Standards]]
* [[PHP Coding Standards]]
* [[ASP Coding Standards]]
* [[Database Standards]]
* [[Site Configuration: CodeIgniter]]

== File Naming Conventions ==

;RULE: Do not place [http://en.wikipedia.org/wiki/Active_Server_Pages ASP] code or any other type of [http://en.wikipedia.org/wiki/Server-side_scripting server side code] in any files other then .asp files.

:'''RATIONAL''': Placing ASP code in files that are not .asp will allow regular users to use a [http://en.wikipedia.org/wiki/Web_browser web browser] to view the source of the code. ASP code in a [http://en.wikipedia.org/wiki/Html .html] page, for example can be viewed by anyone, potentially giving away sensitive information or passwords.

;RULE: Use [http://en.wikipedia.org/wiki/Prefix prefixes] for filenames of pages with similar [http://en.wikipedia.org/wiki/Subroutine functions].  For Example: All the pages dealing with user would be userUpdate.asp, userDisplay.asp.

:'''RATIONAL''': Consistent use of descriptive prefixes assists in [http://en.wikipedia.org/wiki/File_manager file management] and ease of access to needed files.

;RULE: Use descriptive [http://en.wikipedia.org/wiki/Filename filenames] on English. For example: Do Not use a-acc4.asp. Do use a-accApproveCharacterSheet.asp

:'''RATIONAL''': Descriptive file names help with productive file management and each of access to needed files.

[[Category:Coding Standards]]