Advanced Topics: Difference between revisions
Created page with "'''6.1 Coding Conventions''' ---- Coding conventions are a collection of suggestions that can aid in the creation, reading, debugging, and maintaining of programs. Coding conv..." |
No edit summary |
||
| Line 1: | Line 1: | ||
'''6.1 Coding Conventions''' | '''6.1 Coding Conventions''' | ||
---- | ---- | ||
Coding conventions are a collection of suggestions that can aid in the creation, reading, debugging, and maintaining of programs. Coding conventions include, but are not limited to: | Coding conventions are a collection of suggestions that can aid in the creation, reading, debugging, and maintaining of programs. Coding conventions include, but are not limited to: <br /> | ||
• Naming guidelines | • Naming guidelines <br /> | ||
• Text formatting guidelines | • Text formatting guidelines <br /> | ||
• Commenting guidelines | • Commenting guidelines <br /> | ||
Solid coding conventions should help to provide context-sensitive information and improved visual readability. | Solid coding conventions should help to provide context-sensitive information and improved visual readability. | ||
| Line 10: | Line 10: | ||
6.1.1 Naming guidelines | 6.1.1 Naming guidelines | ||
---- | ---- | ||
The easiest way to provide context-sensitive information in a program is by the use of concise, informative names of constants, variable, and procedures. | The easiest way to provide context-sensitive information in a program is by the use of concise, informative names of constants, variable, and procedures. <br /> | ||
Non-trivial names should be as complete as necessary to describe purpose or use. When multiple words are used, vary upper- and lower-case letters and/or use an underscore (_) character to delimit words. | Non-trivial names should be as complete as necessary to describe purpose or use. When multiple words are used, vary upper- and lower-case letters and/or use an underscore (_) character to delimit words. <br /> | ||
Constant names should be all uppercase with an underscore between words. | Constant names should be all uppercase with an underscore between words. <br /> | ||
Variable names should be lower-case with the first letter of each word capitalized; refrain from using underscores in variable names. For additional information, start each variable name with a three letter prefix that describes the type of information that the variable will store (bln for BOOLEAN, int for INTEGER, str for STRING, etc.). | Variable names should be lower-case with the first letter of each word capitalized; refrain from using underscores in variable names. For additional information, start each variable name with a three letter prefix that describes the type of information that the variable will store (bln for BOOLEAN, int for INTEGER, str for STRING, etc.). <br /> | ||
Procedure names should be lower-case with the first letter of each word capitalized. The use of underscores and mixed case will easily differentiate procedure names from constant or variable names. | Procedure names should be lower-case with the first letter of each word capitalized. The use of underscores and mixed case will easily differentiate procedure names from constant or variable names. | ||
| Line 19: | Line 19: | ||
6.1.2 Text formatting guidelines | 6.1.2 Text formatting guidelines | ||
---- | ---- | ||
Text formatting is an excellent way to improve the visual readability of a program. Use white vertically to space to group or separate statements, and horizontally to align statements to show logic structure and nesting. | Text formatting is an excellent way to improve the visual readability of a program. Use white vertically to space to group or separate statements, and horizontally to align statements to show logic structure and nesting. <br /> | ||
Insert a blank line after constant definitions, after variable definitions, and after each procedure declaration to keep sections separated. A blank line can also be inserted after related statements at script level or inside procedures; this will help to form groups. | Insert a blank line after constant definitions, after variable definitions, and after each procedure declaration to keep sections separated. A blank line can also be inserted after related statements at script level or inside procedures; this will help to form groups. <br /> | ||
The standard tab indent is two spaces. Use at least one tab to show nested groups of statements inside procedures, loops, and conditional execution statements. | The standard tab indent is two spaces. Use at least one tab to show nested groups of statements inside procedures, loops, and conditional execution statements. | ||
| Line 26: | Line 26: | ||
6.1.3 Comment guidelines | 6.1.3 Comment guidelines | ||
---- | ---- | ||
Comments should document what the programmer is attempting to do and how, as well as what should be done or what needs to be done. Use comments: | Comments should document what the programmer is attempting to do and how, as well as what should be done or what needs to be done. Use comments: <br /> | ||
• At the top of each program to include information about who wrote it, what services it can provide, when it was written, when updates occurred and what prompted them, and who owns the rights to the program. | • At the top of each program to include information about who wrote it, what services it can provide, when it was written, when updates occurred and what prompted them, and who owns the rights to the program. <br /> | ||
• To preface each procedure with an explanation of the purpose of the procedure along with its expected inputs and any output. An additional line should be included for each variable that is being passed in if its purpose is not obvious or it has range restrictions. | • To preface each procedure with an explanation of the purpose of the procedure along with its expected inputs and any output. An additional line should be included for each variable that is being passed in if its purpose is not obvious or it has range restrictions. <br /> | ||
• To append a brief statement after constant and variable declarations, adding information about scope and usage. | • To append a brief statement after constant and variable declarations, adding information about scope and usage. <br /> | ||
• Above a group of related statements to explain what the statements are doing. | • Above a group of related statements to explain what the statements are doing. <br /> | ||
• In conditional execution statements to further clarify each condition and how it comes about. | • In conditional execution statements to further clarify each condition and how it comes about. | ||
'''6.2 Handling Errors''' | '''6.2 Handling Errors''' | ||
---- | ---- | ||
In a perfect world, there are never any errors. Our programs are seldom perfect worlds! We protect our users (often ourselves) from many errors using two techniques: defensive programming and error trapping. | In a perfect world, there are never any errors. Our programs are seldom perfect worlds! We protect our users (often ourselves) from many errors using two techniques: defensive programming and error trapping. <br /> | ||
The basic idea with error handling is to anticipate which parts of your program could have run-time errors, and to set up special program code to deal with it. | The basic idea with error handling is to anticipate which parts of your program could have run-time errors, and to set up special program code to deal with it. | ||
| Line 43: | Line 42: | ||
6.2.1 Defensive programming | 6.2.1 Defensive programming | ||
---- | ---- | ||
Programming defensively helps to avoid run-time errors by reducing the number of assumptions that are made as the program executes. In addition, you should always do the following: | Programming defensively helps to avoid run-time errors by reducing the number of assumptions that are made as the program executes. In addition, you should always do the following: <br /> | ||
• Initialize variables after they are declared to ensure they hold the proper type of data before they are used. | • Initialize variables after they are declared to ensure they hold the proper type of data before they are used. <br /> | ||
• Use the DIM statement to ensure that all variables are declared before being used. This helps to prevent mistakes from misspelling variable names. | • Use the DIM statement to ensure that all variables are declared before being used. This helps to prevent mistakes from misspelling variable names. <br /> | ||
• Use the VARTYPE function to ensure a variable whose value is input by the user contains the expected data type. | • Use the VARTYPE function to ensure a variable whose value is input by the user contains the expected data type. <br /> | ||
• Check that numeric values are within the valid range before using them in numeric expressions. | • Check that numeric values are within the valid range before using them in numeric expressions. <br /> | ||
• Know the number of elements in an array dimension before trying to access them. | • Know the number of elements in an array dimension before trying to access them. <br /> | ||
The more defensively you program, the less chance there is for run-time errors to occur. A good defensive programmer can eliminate logic errors and protect the program from any errors caused by user interaction. | The more defensively you program, the less chance there is for run-time errors to occur. A good defensive programmer can eliminate logic errors and protect the program from any errors caused by user interaction. | ||
Revision as of 03:10, 1 August 2012
6.1 Coding Conventions
Coding conventions are a collection of suggestions that can aid in the creation, reading, debugging, and maintaining of programs. Coding conventions include, but are not limited to:
• Naming guidelines
• Text formatting guidelines
• Commenting guidelines
Solid coding conventions should help to provide context-sensitive information and improved visual readability.
6.1.1 Naming guidelines
The easiest way to provide context-sensitive information in a program is by the use of concise, informative names of constants, variable, and procedures.
Non-trivial names should be as complete as necessary to describe purpose or use. When multiple words are used, vary upper- and lower-case letters and/or use an underscore (_) character to delimit words.
Constant names should be all uppercase with an underscore between words.
Variable names should be lower-case with the first letter of each word capitalized; refrain from using underscores in variable names. For additional information, start each variable name with a three letter prefix that describes the type of information that the variable will store (bln for BOOLEAN, int for INTEGER, str for STRING, etc.).
Procedure names should be lower-case with the first letter of each word capitalized. The use of underscores and mixed case will easily differentiate procedure names from constant or variable names.
6.1.2 Text formatting guidelines
Text formatting is an excellent way to improve the visual readability of a program. Use white vertically to space to group or separate statements, and horizontally to align statements to show logic structure and nesting.
Insert a blank line after constant definitions, after variable definitions, and after each procedure declaration to keep sections separated. A blank line can also be inserted after related statements at script level or inside procedures; this will help to form groups.
The standard tab indent is two spaces. Use at least one tab to show nested groups of statements inside procedures, loops, and conditional execution statements.
6.1.3 Comment guidelines
Comments should document what the programmer is attempting to do and how, as well as what should be done or what needs to be done. Use comments:
• At the top of each program to include information about who wrote it, what services it can provide, when it was written, when updates occurred and what prompted them, and who owns the rights to the program.
• To preface each procedure with an explanation of the purpose of the procedure along with its expected inputs and any output. An additional line should be included for each variable that is being passed in if its purpose is not obvious or it has range restrictions.
• To append a brief statement after constant and variable declarations, adding information about scope and usage.
• Above a group of related statements to explain what the statements are doing.
• In conditional execution statements to further clarify each condition and how it comes about.
6.2 Handling Errors
In a perfect world, there are never any errors. Our programs are seldom perfect worlds! We protect our users (often ourselves) from many errors using two techniques: defensive programming and error trapping.
The basic idea with error handling is to anticipate which parts of your program could have run-time errors, and to set up special program code to deal with it.
6.2.1 Defensive programming
Programming defensively helps to avoid run-time errors by reducing the number of assumptions that are made as the program executes. In addition, you should always do the following:
• Initialize variables after they are declared to ensure they hold the proper type of data before they are used.
• Use the DIM statement to ensure that all variables are declared before being used. This helps to prevent mistakes from misspelling variable names.
• Use the VARTYPE function to ensure a variable whose value is input by the user contains the expected data type.
• Check that numeric values are within the valid range before using them in numeric expressions.
• Know the number of elements in an array dimension before trying to access them.
The more defensively you program, the less chance there is for run-time errors to occur. A good defensive programmer can eliminate logic errors and protect the program from any errors caused by user interaction.