ASP Coding Standards: Difference between revisions

From Wikipedia of the Dark Brotherhood, an online Star Wars Club
No edit summary
(Marking obsolete)
 
(6 intermediate revisions by 3 users not shown)
Line 1: Line 1:
==Variable Declaration, Naming and Type Notation==
{{Obsolete}}
<center>
{| border="1"
|-
!colspan="3"  |  [[Dark Brotherhood]] Coding Standards
|-
|align="center" colspan="3"  |  [[Coding Standards and Practices]]
|-
| [[ASP Coding Standards]]
| [[CSS Coding Standards]]
| [[Database Standards]]
|-
| [[HTML Coding Standards]]
| [[JavaScript Coding Standards]]
| [[PHP Coding Standards]]


;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.
|}</center>
 
==  Variable Declaration, Naming and Type Notation  ==
 
;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 [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian notation] for naming variables and [http://en.wikipedia.org/wiki/Object_(computer_science) 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.
EXAMPLES:


EXAMPLES:


{| border="1"
{| border="1"  
|-
|-
!Type !! Prefix !! Example
!Type  
 
! Prefix  
 
! Example
|-
|-
|[http://en.wikipedia.org/wiki/String_(computer_science) String] || str || strName
|[http://en.wikipedia.org/wiki/String_(computer_science) String]
| str
| strName
|-
|-
|[http://en.wikipedia.org/wiki/Integer Integer] || Int || intUserId
|[http://en.wikipedia.org/wiki/Integer Integer]
| Int
| intUserId
|-
|-
|Double, [http://en.wikipedia.org/wiki/Floating-point Float] || dbl || dblDollarValue
|Double, [http://en.wikipedia.org/wiki/Floating-point Float]
| dbl
| dblDollarValue
|-
|-
|[http://en.wikipedia.org/wiki/Boolean_data_type Boolean] || bln || blnIsBlank
|[http://en.wikipedia.org/wiki/Boolean_data_type Boolean]
| bln
| blnIsBlank
|-
|-
|[http://en.wikipedia.org/wiki/Recordset Recordset] || rs || rsMembers
|[http://en.wikipedia.org/wiki/Recordset Recordset]
| rs
| rsMembers
 
|}
|}
 
;RULE
;RULE: Use the Hungarian notation for [http://en.wikipedia.org/wiki/Form_(web) form] fields to make forms clearer
: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.
EXAMPLES:


EXAMPLES:


{| border="1"
{| border="1"  
|-
|-
! Form Component !! Prefix
! Form Component  
 
! Prefix
|-
|-
|[http://en.wikipedia.org/wiki/Text_box Input Box] || txtUserName
|[http://en.wikipedia.org/wiki/Text_box Input Box]
| txtUserName
|-
|-
|[http://en.wikipedia.org/wiki/Check_box Check Box] || chkOrder
|[http://en.wikipedia.org/wiki/Check_box Check Box]
| chkOrder
|-
|-
|[http://en.wikipedia.org/wiki/Button_(computing) Button] || btnSubmit
|[http://en.wikipedia.org/wiki/Button_(computing) Button]
| btnSubmit
|-
|-
|Hidden Field || hdnUserId
|Hidden Field
| hdnUserId
 
|}
|}
;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
EXAMPLE: Const MIN_USERS = 3


;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


EXAMPLE: Const MIN_USERS = 3
;RULE
:Variable names should be meaningful and descriptive.


;RULE: Variable names should be meaningful and descriptive.
:'''RATIONAL''': Combined with the Hungarian notation, this leads to clear code, where the purpose and type of each variable is obvious from inspection.
EXAMPLES:


:'''RATIONAL''': Combined with the Hungarian notation, this leads to clear code, where the purpose and type of each variable is obvious from inspection.


EXAMPLES:
{| border="1"
|-
! Good


{| border="1"
! Bad
! Good !! Bad
|-
|-
|strUserName || N
|strUserName
| N
|-
|-
|intUserId || uid
|intUserId
| uid
 
|}
|}
==  Code Documentation  ==
;RULE
:Include a File Information section at the very top of you page, include File Author, Date Created, Description and Date / Description of any changes made to the code.
:'''RATIONAL''': Documenting changes, the authors name and the date of the creation allow for easy understanding of and access to the author in the future.
;RULE
:Document all variables.


== Code Documentation ==


;RULE: Include a File Information section at the very top of you page, include File Author, Date Created, Description and Date / Description of any changes made to the code.
;RULE
:Document all [http://en.wikipedia.org/wiki/Conditional_(programming) conditional statements], explain what it is checking.


:'''RATIONAL''': Documenting changes, the authors name and the date of the creation allow for easy understanding of and access to the author in the future.


;RULE: Document all variables.  
;RULE
:Document all functions, explaining what the function does and what it is returning.


;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 tricky and unusual code.


;RULE: Document all tricky and unusual code.


==Code Structure and Practices==
== Code Structure and Practices ==


;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.  
;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 [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.
:''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


:'''RATIONAL''': Speeds up script processing times. Leads to cleaner code
:'''RATIONAL''': Speeds up script processing times. Leads to cleaner code


;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].  
;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.


;RULE: Indent blocks of code with an indent size of four (4) spaces
;RULE
:Indent blocks of code with an indent size of four (4) spaces


:'''RATIONAL''': Indents allow for easier readability of code. Four spaces is an industry-standard indent.
:'''RATIONAL''': Indents allow for easier readability of code. Four spaces is an industry-standard indent.


;RULE: Use white space to separate those blocks.  
;RULE
:Use white space to separate those blocks.


:'''RATIONAL''': White space allows for easier readability of code
:'''RATIONAL''': White space allows for easier readability of code


;RULE: Put all file includes below the File Information comment block.  
;RULE
:Put all file includes below the File Information comment block.


:'''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 [http://en.wikipedia.org/wiki/Global_variable 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


;RULE: Put the ASP delimiters <% %> on the left hand margin.  
;RULE
:Put the ASP delimiters &lt;% %&gt; on the left hand margin.


:'''RATIONAL''': Allows for easier readability of code. Makes it easier to distinguish code blocks.  
:'''RATIONAL''': Allows for easier readability of code. Makes it easier to distinguish code blocks.


;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 [http://en.wikipedia.org/wiki/Database 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


:'''RATIONAL''': Subs are built to be used without returning a value. Using them in the place of functions increases code readability and processing speed.  
:'''RATIONAL''': Subs are built to be used without returning a value. Using them in the place of functions increases code readability and processing speed.


;RULE: Dim and fill variables for items pulled from the Request(“”) object rather than calling the Request(“”) object continuously.
;RULE
:Dim and fill variables for items pulled from the Request(“”) object rather than calling the Request(“”) object continuously.


:'''RATIONAL''': Using variables filled from the Request(“”) Object allows for easier readability of the code, as the coder can document what the data being pulled from the object is. Continued use of variables is also faster to process than Request(“”) calls and less confusing.
:'''RATIONAL''': Using variables filled from the Request(“”) Object allows for easier readability of the code, as the coder can document what the data being pulled from the object is. Continued use of variables is also faster to process than Request(“”) calls and less confusing.


==Common Names and Customs==
== Common Names and Customs ==
 
[[Category:Coding Standards]]
*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 variable named “strErrorMsg” to hold [http://en.wikipedia.org/wiki/Error_message error messages] from the page
 
[[Category: DJB Info]][[Category:Coding Standards]]

Latest revision as of 00:41, 21 April 2024

You must unlearn what you have learned.
This article contains obsolete data. It reflects a Dark Brotherhood policy, position, or object that has been removed or replaced. It is preserved here for historical purposes only and should not be used/referenced.
Dark Brotherhood Coding Standards
Coding Standards and Practices
ASP Coding Standards CSS Coding Standards Database Standards
HTML Coding Standards JavaScript Coding Standards PHP Coding Standards

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

EXAMPLES:


Type Prefix Example
String str strName
Integer Int intUserId
Double, Float dbl dblDollarValue
Boolean bln blnIsBlank
Recordset rs rsMembers
RULE
Use the Hungarian notation for 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.

EXAMPLES:


Form Component Prefix
Input Box txtUserName
Check Box chkOrder
Button btnSubmit
Hidden Field hdnUserId
RULE
Use all uppercase when declaring a const variable
RATIONAL: Using all uppercase letters for constants helps to clearly indicate which variables are constants without referring to the declaration

EXAMPLE: Const MIN_USERS = 3


RULE
Variable names should be meaningful and descriptive.
RATIONAL: Combined with the Hungarian notation, this leads to clear code, where the purpose and type of each variable is obvious from inspection.

EXAMPLES:


Good Bad
strUserName N
intUserId uid

Code Documentation

RULE
Include a File Information section at the very top of you page, include File Author, Date Created, Description and Date / Description of any changes made to the code.
RATIONAL: Documenting changes, the authors name and the date of the creation allow for easy understanding of and access to the author in the future.
RULE
Document all variables.


RULE
Document all conditional statements, explain what it is checking.


RULE
Document all functions, explaining what the function does and what it is returning.


RULE
Document all tricky and unusual code.


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.
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.
RULE
Combine multiple "Response.Write" lines into one larger single statement whenever possible
RATIONAL: Speeds up script processing times. Leads to cleaner code
RULE
Use arrays rather 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.
RULE
Indent blocks of code with an indent size of four (4) spaces
RATIONAL: Indents allow for easier readability of code. Four spaces is an industry-standard indent.
RULE
Use white space to separate those blocks.
RATIONAL: White space allows for easier readability of code
RULE
Put all file includes below the File Information comment block.
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.
RATIONAL: Global variables should be declared at the top of the file to increase ease of use and notice of what they are
RULE
Put the ASP delimiters <% %> on the left hand margin.
RATIONAL: Allows for easier readability of code. Makes it easier to distinguish code blocks.
RULE
Use all lowercase when writing HTML tags
RATIONAL: Allows for easier readability of code, lowers confusion with Database calls and Constant declarations.
RULE
Use “Sub” rather than “Function” for functions that have no return value
RATIONAL: Subs are built to be used without returning a value. Using them in the place of functions increases code readability and processing speed.
RULE
Dim and fill variables for items pulled from the Request(“”) object rather than calling the Request(“”) object continuously.
RATIONAL: Using variables filled from the Request(“”) Object allows for easier readability of the code, as the coder can document what the data being pulled from the object is. Continued use of variables is also faster to process than Request(“”) calls and less confusing.

Common Names and Customs