Detailed Instructions for Course Work Submissions

    /***********************************************************************
     * Name(s)  (identify both lab partners for labs, projects)            *
     * Box(s):                                                             *
     * Assignment name (Lab, Project, Sup. Problem Number _______)         *
     *      (25% off if name/number does not match assignment)             *
     * Assignment for <due date>                                           *
     ***********************************************************************/

    /* *********************************************************************
     * Academic honesty certification:                                     *
     *   Written/online sources used:                                      *
     *     [include textbook(s), CSC 115 labs or readings;                 *
     *       complete citations for Web or other written sources           *
     *      write "none" if no sources used]                               *
     *   Help obtained                                                     *
     *     [indicate names of instructor, class mentors                    *
     *      or evening tutors, consulted according to class policy;        *
     *      write "none" if none of these sources used]                    *
     *     ["none" required for Supplemental Problems                      *
     *   My/our signature(s) below confirms that the above list of sources *
     *   is complete AND that I/we have not talked to anyone else          *
     *   (e.g., CSC 115 students) about the solution to this problem       *
     *                                                                     *
     *   Signature:                                                        *
     ***********************************************************************/

No coursework can be accepted, if this certification is incomplete or if the statement is not signed by ALL collaborators involved.

• All code must use a fixed-width font (e.g., Courier). Use of emacs, aquamacs, TextEdit (for Macs), or NotePad/WordPad (for Windows 10) (with the default font) is strongly encouraged.
• Use of variable-width fonts (e.g., from a word processing package) is disqualifying for code — spacing with variable-width fonts is unreliable, and code structure is likely lost. Code using variable-width fonts will be returned without grading.
• Output, if given, must utilize a fixed-width font.
• Commentary (e.g., answers to lab questions, discussions of testing and correctness) may be in either a fixed-width font or a variable-width font.

• Answers to questions should be numbered and in numeric order (e.g., the answer to Step 1 should be numbered 1 and come before the answer to Step 2).
• Explanations and answers to questions may be given in any word processing (e.g., emacs, vi, LibreOffice (for Linux), pages (for Macs), Word (for Windows 10), etc.)
• Answers involving code may be copied and pasted (with a fixed-width font) into the general commentary or printed as separate files. If code-based answers are separate, comments in the code must specify the section for each answer.
• Commentary may involve either fixed-width fonts or variable-width fonts.

• A complete program should be given as a single entity, unless otherwise specified in the instructions; the program should not be printed in pieces — various pieces on separate pieces.
• Commentary regarding testing should be given in a separate file, not included within the complete program.

• Code should be divided into appropriate functions and procedures. A simple block of code need not be encapsulated within a function, but long, complex code segments should be organized into pieces.
• Global variables are almost never appropriate. Use parameters to send data to functions and procedures.
• Indenting of code must show the structure of the code.
  • Indenting must be consistent.
  • Code within a conditional statement must be indented within the corresponding if or switch.
  • Code within a loop must be indented.
  • Code within a function must be indented within the function.
  • Code within the same logical code segment must be indented consistently.
• Each function and the main program must contain comments including
  • A statement of what the function or program does
  • A statement of any pre-conditions (or pre-conditions: none)
  • A statement of post-conditions
• Code should contain comments to provide insight into the structure and approach of a program.
  • Comments should describe each logical section of the code (e.g., main steps, elements of the algorithm or data structure).
  • Comments should NOT simply repeat the code. For example, the following comment duplicates the code and sidetracks the reader.

          int x = 7; /* x is declared as an integer variable with initial value 7 */
    

  • Within a program to compute mortgage payments, program mortgage-good-comments.c illustrates comments that add insight and clarity. In contrast, program mortgage-poor-comments.c includes extensive commentary, but the comments add no insight and mostly get in the way of reading the code.
• Although programs need not be the most efficient possible, inefficient code may not earn many points.
  • Sorting normally should use an insertion sort (as covered in this course).
  • If another sorting algorithm is to be considered, approval in advanced is needed from the instructor.
  • Bubble sort is never appropriate in any context, since it is remarkably inefficient. Any program containing a bubble sort will immediately be give 0 points.

• Commentary within a program should describe any complex data structures and identify main steps of a complicated algorithm. There is no need to repeat simple steps in code, but clarification is important when data structures or algorithms are complex.
• A separate commentary should describe how one knows a program is correct. As with any writing, this commentary should be logically structured and carefully written.

• If the program always does the same activities (e.g., plays a song), describe what the robot does and why you think this is the proper result.
• If the robot reacts to input or its environment, describe the situations that can occur, how you tested each circumstance, and how the robot responded.
  
  For example, if the robot is to move and avoid obstacles, testing should identify that no obstacles might be present, a obstacle may exist on the left, an obstacle on the right, or an obstacle on both left and right. In each case, commentary should describe what tests were run and how the robot reacted.

• All code must be tested; commentary must address the basic question of how you know the code is correct.
• Commentary that simply repeats the logic of the program does not address correctness. If the logic in a program is faulty, simply stating the logic again does not make it correct.
• Evidence based on testing must be described.
  • What circumstances can arise in the problem?
  • What test cases have been devised to check those circumstances?
  • What results does the program produce for those test cases? For example, program output should be copied into your commentary. In order to analyze the output, be sure to include a clear statement of what input was used for each test.
  • Are the results correct, and how do you know?

• Turn in a printed copy of your answers to questions, as well as programs, code segments, and relevant output.
  • A printed copy of your answers should be on top. (Since your name, box, etc. are required to be at the start of the your answers, this printout will identify that this is your work.)
  • If your work involves several files, list the main program first; then list any supplementary files.

• No electronic submissions are expected for labs!

• Turn in a printed copy of your program, relevant output, and a discussion of testing.
  • A printed copy of the program should be on top. (Since your name, box, etc. are required to be at the start of the program, this printout will identify that this is your work.)
  • If your work involves several files, list the main program first; then list any supplementary files.
  • Write a separate statement, not in the program, that documents the testing process for this program. The statement should include:
    • A numbered listing of the circumstances that can reasonably arise in this problem.
      • For example, if a program is to categorize data, the listing should include a statement of the categories; If some category could be obtained in several ways, the statement should identify each circumstance that could lead to the category.
      • As another example, if the order of initial data might impact processing, then the listing should include circumstances to test the order of input data.
    • A listing of test cases to be considered, with the expected outcome.
      • For each numbered item in the listing of possible circumstances, there should be a corresponding test case identified.
      • Each test case should be specific, including what data will be considered and what output is expected.
  • Compile your program with the gcc command, and run it.
    • If the program does not use the Scribbler 2, include the full range of test cases that demonstrate the correctness of your program. (You should print the full interaction from the terminal during the test runs.)
    • If the program uses the Scribbler 2, include a description of what test runs you used and what results you obtained.
    • The actual test runs should follow the above listing of test cases.
    • Each test run should be annotated (writing on the printout is acceptable), identifying which test case is being run and whether or not the output produced is correct.
  • Once testing is completed, prepare a separate statement that argues why your program is correct, based upon the evidence from your test runs.