|
|
Line 1: |
Line 1: |
| {{underlinked}}
| |
| =Coding Standards and Practices= | | =Coding Standards and Practices= |
|
| |
|
| ==Introduction== | | ==Introduction== |
| One of the most important aspects of coding websites for use within the Dark Brotherhood is the ability of future generations of members to be able to successfully use and modify the code to fit their needs. Unfortunately, many 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. | | 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 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. | | |
| | 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. |
|
| |
|
| ==Files== | | ==Files== |
|
| |
|
| ;RULE: Do not place ASP code or any other type of server side code in any files other then .asp files. | | ;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 web browser to view the source of the code. ASP code in a .html page, for example can be viewed by anyone, potentially giving away sensitive information or passwords. | | :'''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: Any pages that do not use server side code of some sort should use the .html extension | | ;RULE: Any pages that do not use server side code of some sort should use the .html [http://en.wikipedia.org/wiki/Filename_extension extension] |
|
| |
|
| :'''RATIONAL''': Many sites use custom page extensions that are not .html. This causes problems in some browsers. For consistency and maximum compatibility, .html should be used throughout. | | :'''RATIONAL''': Many sites use custom page extensions that are not .html. This causes problems in some browsers. For consistency and maximum compatibility, .html should be used throughout. |
|
| |
|
| ;RULE: Use prefixes for filenames of pages with similar functions. For Example: All the pages dealing with user would be userUpdate.asp, userDisplay.asp. | | ;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 file management and ease of access to needed files. | | :'''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 filenames. For example: Do Not use a-acc4.asp. Do use a-accApproveCharacterSheet.asp | | ;RULE: Use descriptive [http://en.wikipedia.org/wiki/Filename filenames]. 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. | | :'''RATIONAL''': Descriptive file names help with productive file management and each of access to needed files. |
Line 26: |
Line 26: |
| ==Variable Declaration, Naming and Type Notation== | | ==Variable Declaration, Naming and Type Notation== |
|
| |
|
| ;RULE: Each variable should be dimmed and initialized at the start of the appropriate code section. “Option Explicit” should be declared at the very start of each .asp file. Variables should be commented to display their use. | | ;RULE: Each [http://en.wikipedia.org/wiki/Variable_(programming) variable] should be dimmed and initialized at the start of the appropriate code section. “Option Explicit” should be declared at the very start of each .asp file. Variables should be commented to display their use. |
|
| |
|
| :'''RATIONAL''': Using Option Explicit forces the coder to dim variables before they are used. Dimming variables and initializing them to the proper values speeds up the processing of the page. | | :'''RATIONAL''': Using Option Explicit forces the coder to dim variables before they are used. Dimming variables and initializing them to the proper values speeds up the processing of the page. |
|
| |
|
| ;RULE: Use the Hungarian notation for naming variables and objects. | | ;RULE: Use the [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation] for naming variables and [http://en.wikipedia.org/wiki/Object_(computer_science) objects]. |
|
| |
|
| :'''RATIONAL''': The purpose of the Hungarian notation is to be able to interpret the type and purpose of a variable without having to search through the code for its use. | | :'''RATIONAL''': The purpose of the Hungarian notation is to be able to interpret the type and purpose of a variable without having to search through the code for its use. |
Line 40: |
Line 40: |
| !Type !! Prefix !! Example | | !Type !! Prefix !! Example |
| |- | | |- |
| |String || str || strName | | |[http://en.wikipedia.org/wiki/String_(computer_science) String] || str || strName |
| |- | | |- |
| |Integer || Int || intUserId | | |[http://en.wikipedia.org/wiki/Integer Integer] || Int || intUserId |
| |- | | |- |
| |Double, Float || dbl || dblDollarValue | | |Double, [http://en.wikipedia.org/wiki/Floating-point Float] || dbl || dblDollarValue |
| |- | | |- |
| |Boolen || bln || blnIsBlank | | |[http://en.wikipedia.org/wiki/Boolean_data_type Boolean] || bln || blnIsBlank |
| |- | | |- |
| |Recordset || rs || rsMembers | | |[http://en.wikipedia.org/wiki/Recordset Recordset] || rs || rsMembers |
| |} | | |} |
|
| |
|
|
| |
|
| ;RULE: Use the Hungarian notation for form fields to make forms clearer | | ;RULE: Use the Hungarian notation for [http://en.wikipedia.org/wiki/Form_(web) form] fields to make forms clearer |
|
| |
|
| :'''RATIONAL''': The purpose of the Hungarian notation is to be able to interpret the type and purpose of a field without having to search through the code for its use. | | :'''RATIONAL''': The purpose of the Hungarian notation is to be able to interpret the type and purpose of a field without having to search through the code for its use. |
Line 62: |
Line 62: |
| ! Form Component !! Prefix | | ! Form Component !! Prefix |
| |- | | |- |
| |Input Box || txtUserName | | |[http://en.wikipedia.org/wiki/Text_box Input Box] || txtUserName |
| |- | | |- |
| |Check Box || chkOrder | | |[http://en.wikipedia.org/wiki/Check_box Check Box] || chkOrder |
| |- | | |- |
| |Button || btnSubmit | | |[http://en.wikipedia.org/wiki/Button_(computing) Button] || btnSubmit |
| |- | | |- |
| |Hidden Field || hdnUserId | | |Hidden Field || hdnUserId |
Line 72: |
Line 72: |
|
| |
|
|
| |
|
| ;RULE: Use all uppercase when declaring a const variable | | ;RULE: Use all uppercase when declaring a [http://en.wikipedia.org/wiki/Constant_%28programming%29 const] variable |
|
| |
|
| :'''RATIONAL''': Using all uppercase letters for constants helps to clearly indicate which variables are constants without referring to the declaration | | :'''RATIONAL''': Using all uppercase letters for constants helps to clearly indicate which variables are constants without referring to the declaration |
Line 102: |
Line 102: |
| ;RULE: Document all variables. | | ;RULE: Document all variables. |
|
| |
|
| ;RULE: Document all conditional statements, explain what it is checking. | | ;RULE: Document all [http://en.wikipedia.org/wiki/Conditional_(programming) conditional statements], explain what it is checking. |
|
| |
|
| ;RULE: Document all functions, explaining what the function does and what it is returning. | | ;RULE: Document all functions, explaining what the function does and what it is returning. |
Line 110: |
Line 110: |
| ==Code Structure and Practices== | | ==Code Structure and Practices== |
|
| |
|
| ;RULE: Avoid context switching such as switching between ASP and HTML or switching between VBscript and Jscript on the same page. Try to perform all server side code at the top of your page before executing any HTML code. | | ;RULE: Avoid [http://en.wikipedia.org/wiki/Context_switch context switching] such as switching between ASP and HTML or switching between [http://en.wikipedia.org/wiki/VBscript VBscript] and [http://en.wikipedia.org/wiki/JScript Jscript] on the same page. Try to perform all server side code at the top of your page before executing any HTML code. |
|
| |
|
| :''RATIONAL''': Switching between ASP and HTML causes a slow down in script processing time and leads to sloppy code. Forcing the ASP code at the top of the page requires planning and forethought from the coder. | | :''RATIONAL''': Switching between ASP and HTML causes a slow down in [http://en.wikipedia.org/wiki/Scripting_language script] processing time and leads to sloppy code. Forcing the ASP code at the top of the page requires planning and forethought from the coder. |
|
| |
|
| ;RULE: Combine multiple "Response.Write" lines into one larger single statement whenever possible | | ;RULE: Combine multiple "Response.Write" lines into one larger single statement whenever possible |
Line 118: |
Line 118: |
| :'''RATIONAL''': Speeds up script processing times. Leads to cleaner code | | :'''RATIONAL''': Speeds up script processing times. Leads to cleaner code |
|
| |
|
| ;RULE: Use arrays rather than dictionary objects or collections. | | ;RULE: Use [http://en.wikipedia.org/wiki/Array arrays] rather than [http://en.wikipedia.org/wiki/Associative_array dictionary objects] or [http://en.wikipedia.org/wiki/Collection_(computing) collections]. |
|
| |
|
| :'''RATIONAL''': Arrays are always faster and more efficient than other storage methods and use less memory than dictionary objects or collections. | | :'''RATIONAL''': Arrays are always faster and more efficient than other storage methods and use less memory than dictionary objects or collections. |
Line 134: |
Line 134: |
| :'''RATIONAL''': Having includes at the top of the page instantly allows the coder to see what the file is referencing and follows the dichotomy calling for ASP to be at the top of the page. | | :'''RATIONAL''': Having includes at the top of the page instantly allows the coder to see what the file is referencing and follows the dichotomy calling for ASP to be at the top of the page. |
|
| |
|
| ;RULE: Declare all global variables below the file includes. | | ;RULE: Declare all [http://en.wikipedia.org/wiki/Global_variable global variables] below the file includes. |
|
| |
|
| :'''RATIONAL''': Global variables should be declared at the top of the file to increase ease of use and notice of what they are | | :'''RATIONAL''': Global variables should be declared at the top of the file to increase ease of use and notice of what they are |
Line 144: |
Line 144: |
| ;RULE: Use all lowercase when writing HTML tags | | ;RULE: Use all lowercase when writing HTML tags |
|
| |
|
| :'''RATIONAL''': Allows for easier readability of code, lowers confusion with Database calls and Constant declarations. | | :'''RATIONAL''': Allows for easier readability of code, lowers confusion with [http://en.wikipedia.org/wiki/Database Database] calls and Constant declarations. |
|
| |
|
| ;RULE: Use “Sub” rather than “Function” for functions that have no return value | | ;RULE: Use “Sub” rather than “Function” for functions that have no return value |
Line 156: |
Line 156: |
| ==Database Calls and Structure== | | ==Database Calls and Structure== |
|
| |
|
| ;RULE: Use all CAPITAL LETTERS for Common SQL commands. Ex: “SELECT Member_ID FROM Members WHERE…” | | ;RULE: Use all CAPITAL LETTERS for Common [http://en.wikipedia.org/wiki/SQL SQL] commands. Ex: “SELECT Member_ID FROM Members WHERE…” |
|
| |
|
| :'''RATIONAL''': Allows for increased SQL statement readability | | :'''RATIONAL''': Allows for increased SQL statement readability |
|
| |
|
| ;RULE: Avoid “SELECT *” statements. Use “SELECT field1, field2, field3…” | | ;RULE: Avoid “[http://en.wikipedia.org/wiki/Select_(SQL) SELECT] *” statements. Use “SELECT field1, field2, field3…” |
|
| |
|
| :'''RATIONAL''': Allows for increased SQL statement readability and cuts down on transfer of unneeded data | | :'''RATIONAL''': Allows for increased SQL statement readability and cuts down on transfer of unneeded data |
|
| |
|
| ;RULE: Normalize tables where possible | | ;RULE: [http://en.wikipedia.org/wiki/Normalization Normalize] tables where possible |
|
| |
|
| :'''RATIONAL''': Increases the speed of data processing | | :'''RATIONAL''': Increases the speed of data processing |
Line 181: |
Line 181: |
| *Use a variable named “Abort” to dictate whether or not the script should abort from errors in the form data or script. | | *Use a variable named “Abort” to dictate whether or not the script should abort from errors in the form data or script. |
| *Use a hidden field called “hdnSubmitted” that is set to true to dictate to the script that a form has been submitted | | *Use a hidden field called “hdnSubmitted” that is set to true to dictate to the script that a form has been submitted |
| *Use a variable named “strErrorMsg” to hold error messages from the page | | *Use a variable named “strErrorMsg” to hold [http://en.wikipedia.org/wiki/Error_message error messages] from the page |
|
| |
|
| ==Peer Review== | | ==Peer Review== |
|
| |
|
| *Prior to launch of the script, another members of the SCL staff (hopefully your superior) should review your code | | *Prior to launch of the script, another members of the [[Seneschal|SCL]] staff (hopefully your superior) should review your code |
|
| |
|
| ==Development Site and Testing== | | ==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. | | *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 dossiers. | | *Pages should be thoroughly tested on the Development site using the development database and [[Dossier|dossiers]]. |
| *After pages are tested and reviewed, they may be copied to the live server. | | *After pages are tested and reviewed, they may be copied to the live server. |
|
| |
|