PROGRAMMING STYLE STANDARDS

General Program Style

• Variable names should be mnemonic, clear and simple, e.g., "largest" rather than "x".
• Expressions should be clear and simple, e.g., "abs(x) <= 0.01" rather than "(x < 0.01) and (x > -0.01)".
• Indentation and format
  1. Indent bodies of structured statements at least 2 spaces.
  2. Leave blank lines between logically related groups of statements, after the declarations, and between functions.
  3. Surround all operators (==, +, <, etc.) with blanks.
  4. Wrap long lines at no more than 80 characters and indent the continued statement further than the beginning of that statement
  5. Clearly delineate subprograms (procedures, functions, modules).
• Make use of the features of the language, i.e., if the language has a useful built-in feature, use it.
• Procedure and function names should be mnemonic.
• Local variables should be declared at the beginning of the function.

Commenting

• All programs should begin with a preface stating:
  1. Name of this program's file.
  2. Programmer's name.
  3. Date written.
  4. Course and section number.
  5. Name of the assignment.
  6. A summary or description of functionality, i.e., what the program does and a brief description of how it does it.
  7. Any known assumptions built into the program.
  8. Any special instructions on how to run it.
• All variables should have a brief comment explaining their purpose. Looping control variables such as: "x" or "i" need not be commented.
• Comments within code should explain tricky or complicated code.
• Comments should be clearly organized and easily distinguishable from the actual code.
• Comments should be comprehensible and useful. Comments such as: "This adds 1 to M" are trivial and should be avoided.
• Comments should be indented to at least the level of the statements they describe.
• Each procedure or function should have a brief comment explaining the purpose of the procedure or function. The comments might also state the limitations of the procedure and/or function using possibly pre-conditions and post-conditions.

Program Robustness

• Do not check for equality among real numbers.
• Prevent the abnormal termination of a program due to input error, check for the validity of the data when appropriate.
• Programs should not be built around a specific data set. Programs, unless otherwise stated, should work correctly for any reasonable test data set.
• Do not use GOTO statements.

I/O Behavior

• All I/O should use a proper format:
  1. All real number output should be formatted in decimal form unless scientific notation is appropriate.
  2. All input from the keyboard should be preceded by a prompt telling the user what format is expected. For example, "Please Input the Date in mm/dd/yy format".
• Label all output values. Remember, the output of a very complicated and elegant program is useless unless one knows how to interpret the output.

Modules and Modular Program Structure

• Module coherence: each module should correspond to one subtask in the overall algorithm to solve the problem.
• Module independence: each module should be independent, i.e., it should be self-contained and it should perform its task successfully without needing to know the inner workings of the calling module.
• Procedures or functions should, in general, occupy at most 50 lines.
• Use appropriate parameters rather than global variables. Avoid side effects.
• Hide any information from the caller that it does not need. The default should be to hide information unless the caller actually needs it.

Program Testing

• The program should follow the program specifications delineated in the problem statement.
• Testing should be sufficient to thoroughly check all parts of the program.
• Make sure that the output of your program illustrates that it does in fact solve the problem.