Programming Guidelines #

For each program, you must work individually unless instructed otherwise. You may discuss the problem with classmates, but at no time should you discuss code in any form. You may not show another student your code, share your file with another student, look at another student’s code, or tell another student what to type. Evidence of academic dishonesty will result in a score of zero (see Academic Integrity section of syllabus). This applies to all students involved. If you’re unsure about something, ask in advance.
Your program must adhere to the problem statement requirements and coding standards below. Violations will lead to deductions.
1. A header comment must be included at the top of each submitted file. Submissions without this header comment will receive a grade of zero. The header comment must consist of the following information, including documentation annotations (annotations begin with the character @):
```
 /**
  *  @file FILE_NAME
  *  @author YOUR_NAME
  *  @date THE_DATE
  *  @note I pledge my word of honor that I have complied with the
  *  CSN Academic Integrity Policy while completing this assignment.
  *  @brief A brief description of the program (no more
  *  than one or two paragraphs)
  *  @note Time taken to develop, write, test and debug solution.
  */
```
  - Failure to disclose assistance, regardless of source, may be interpreted as academic dishonesty.
2. Basic blocks:
  1. Blocks will always use braces using methods demonstrated in class. Brace placement is at your discretion, but must be consistent.
  2. Statements in the block should be indented consistent with logical nesting. Use 4 spaces per indent level. Do not use tabs.
3. Variables:
  1. Variables should be declared at the beginning of the block of code in which they’re used.
  2. Use descriptive names for variables using naming standards discussed in class.
  3. Reduce the scope of variables so that they are only visible in the scope where they’re used. Global variables are never permitted; global constants are permitted, when appropriate.
  4. Use one declaration for each variable (i.e., do not use the comma operator to declare multiple variables at one time). Variable declarations must appear at the beginning of the block of code in which they’re used (i.e., do not intermix declarations with code).
  5. Document the purpose of every identifier you create (e.g., constants, variables, functions, etc.).
  6. Variable declarations should appear at the beginning of the block of code in which they’re used. Do not intermix declarations with code.
4. Statements:
  1. No more than one statement may be written on a single line.
  2. The following may not be used: ‘continue’, ‘goto’, and ‘break’ not in a switch structure.
  3. The use of ’exit’ should be reserved for unrecoverable errors only (e.g., failed memory allocation). Handle errors graciously wherever possible.
  4. Lines of code should be no more than 80 characters long.
  5. Diagnostic/debug print statements should be disabled/deleted in the final submission (i.e., submit a “shipping” version of your program). In advanced courses, use conditional compilation to enable/disable debugging statements.
5. Functions:
  1. Use descriptive names for functions using naming standards discussed in class.
  2. All functions must be documented with the following information:
    1. Purpose - A statement or a set of statements that describes the purpose of the function.
    2. Parameter(s) - The purpose of each parameter should be described.
    3. Return value - For value-returning functions only, describe what the function returns.
    4. When using a single source code file, function documentation should be placed in comments directly above the function definition, not the prototype.
    5. When implementing a large project with multiple source code files, function documentation should be placed in comments directly above the function prototypes in the interface file, not in the implementation file.
    Example function documentation header:
```
 /**
  *  @brief The function foo.
  *
  *  Description of what the function does. This part may refer to the
  *  parameters of the function, like @p param1 or @p param2.
  *
  *  @param param1 Description of the first parameter of the function.
  *  @param param2 The second parameter, which follows @p param1.
  *  @return Describe what the function returns.
  *
  *  @see http://website/
  *  @note Something to note.
  *  @warning Warning.
  */

 int foo(int param1, int param2);
```
  3. Function bodies should not be of extended length when easily separated into multiple functions (i.e., functions should do one thing and nothing more).
  4. Non-recursive functions should contain exactly one return statement. Functions should have one entry point and one exit point (i.e., non-recursive functions should have no more than one return statement).
Programs must be submitted on time. Late programs or programs with syntax errors (i.e., do not compile due to errors) will receive a grade of zero. Your program must compile cleanly (i.e., no warnings) and execute properly on the bellagio server for credit.
It is better to submit a partially correct program that compiles than no program at all.
Submit the program file(s) electronically using the procedure shown on the problem statement requirements. You may submit your program file(s) as many times as you want before the deadline. Each submission will replace any earlier submission, so I can only see and grade your most recent submission. Be sure to submit all required files with each submission. You cannot submit after the deadline (i.e., the drop box is closed).