<

Programming Standards

The Programming Standards from the Operations Research Department at Naval Postgraduate School (NPS) have been adapted here as a guideline.

Documentation in the Source Code
  • Each program must begin with comments that include your name, course and segment number, and the date.
  • Statements that are included in a block of code must be indented three spaces. Be consistent. Such blocks include subs or functions, repetition structures, and selection structures. See examples below.
  • At least one space must appear before each operator as well as the equal sign. The comment symbol should also be preceded and followed by a space.
  • Each procedure must have brief comments at the beginning that describe what the procedure does. Clearly indicate both incoming and outgoing parameters. Studies have shown that general descriptions at the beginning of each procedure are more valuable than comments distributed throughout the code. The comments should cover what the code does rather than how the code does it. (You can trace the code to see how it works.)
  • Comments and blank lines that indicate the major sections of the program are useful. Precede each procedure with two to three blank lines.
  • If (and only if) the meaning of a statement or group of statements is not clear from reading the code, brief comments may be included in the body of the program. In general, these comments are not useful. If they merely state what is obvious from reading the code, they detract. If these comments are necessary, place them at the beginning of the block of code. This will reduce their disruption to the structure of the program.
  • Variable and procedure names should be chosen to help describe their meaning. A poorly chosen name that misleads the reader is worse than a nondescript name like X or A. Variable names must be written with lowercase letters, except for the first letter of embedded words which are written in uppercase, such as taxRate, numberOfCars, and so on.
  • Object classes and variables begin with an uppercase letter. Method names begin with an uppercase letter.
  • Each control object name begins with a lowercase, three-letter prefix that indicates the type of control object. For instance, a form begins with frm, a text box with txt, and a command button with cmd. The remainder of the name describes the control's purpose or contents. For example, txtLastName is a text box containing the last name. See the table below for all of the prefixes.

    Object Type Naming Convention
    Form frm
    Command Button cmd
    List Box lst
    Combo Box cmb
    Text Box txt
    Label / 3D Label lbl
    Grid Control grd
    Option Button / 3D Option Button opt
    Check Box / 3D Check Box chk
    File List Box fil
    Directory List Box dir
    Class cls

Software Engineering Standards

  • All real and double constants must have a decimal point with a digit on each side.
  • Mixed-mode arithmetic is arithmetic containing variables of different data types. When possible, avoid mixed-mode arithmetic expressions and mixed-mode variable assignments. Use the data type conversion functions as necessary.

    CBool Converts the string to a Boolean.
    CByte Converts the string to a Byte.
    CDate Converts the string to a Date.
    CDbl Converts the string to a Double.
    CDec Converts the string to a Decimal.
    CInt Converts the string to a Integer.
    CLng Converts the string to a Long.
    CSng Converts the string to a Single.
    CStr Converts the string to a String.


  • When converting a string to an equivalent numeric value, use the Val function. When converting a numeric value to a string, use the ToString function.
  • Expressions containing multiple operators and operators of different types must have parentheses for clarity and to indicate precedence.
  • All variables must be declared. Variable declarations must appear at the beginning of their procedure.
  • Unnecessary code should be removed. This is particularly important when the code is inside of a loop that will be executed numerous times. It is not necessary to assign the value zero to a variable or array element before it is assigned a value by another statement.
  • Avoid global (form level) variables. There are potential problems when more than one function or procedure uses the same variable; one may change the value of a global variable that would then have an impact on another's use of the variable. Sharing variables by passing them as parameters is preferred because it makes the shared use explicit.

User Interface
  • Visual Basic has many different user controls command buttons, option buttons, drop-down menus, and so on. The user interface that you select should reflect the best user control for the task at hand. For example, if the user must select from several mutually exclusive options, the best choice would be option buttons.
  • Consistency is a key factor for usability. Use standard dialog boxes whenever possible. For example, there is little benefit in inventing your own dialog box to open a file. Use the common dialog control.
  • Plan multiple form interfaces carefully. Be sure that you group items in a form in a logical and consistent manner. Avoid the extremes of too many forms or a form that is so overpowering that it is difficult to comprehend.

Error Prevention
  • For each division operation, there should be either a test to determine that the divisor is not equal to zero or a comment that explains why it can never be equal to zero.

Indentation and Blocks
  • Indentation is an extremely important element of readability. Statements within a procedure should be indented three spaces. The body of the loop should be indented three more spaces. An example follows:

    loop

  • Nested loops follow the same pattern, as in the following example:

    Nested loop.

  • Statements within a decision structure should be indented three spaces, as shown in the following example:

    Decision.

  • Nested If statements follow the same pattern as shown below:

    Nested Decision.

Repetition

C#.Net has multiple repetition constructs. For some repetition situations in a program there is only one possible repetition construct that can be used. In most situations there is a choice. Each repetition construct was designed for a specific situation: therefore, it is possible to develop standards that will dictate the appropriate repetition to use in most programming situations. The following guidelines almost always dictate the appropriate choice:

  • All loops but the For/Next loop are called indefinite (or indeterminate) repetition structures because the number of times that the loop is executed depends upon calculations within the loop. In contrast, the For/Next construct is called a definite (or determinate) repetition structure because the number of executions of the loop (if any) is determined before any execution of the loop. When possible, use definite repetition structure (that is, a For/Next) rather than an indefinite one.
  • In choosing between the Do While-Loop and Do-Loop Until constructs, if the loop must be executed at least once, then the the Do/Loop While and Do/Loop Until are the appropriate choice because in those structures the loop will be executed at least once. Thus, the While, the Do While/Loop, and the Do Until/Loops are used exclusively in situations where the loop may not be executed at all depending on the value of the logical expression.
  • Never use an Exit statement to break out of a loop.