CS 113 - Introduction to Computer Science II with Intensive C
Spring 1999
Homework and Documentation Guidelines

Ethical Policy

Homeworks, programs and examinations have to be completed without collaboration with any other person. You may discuss with your colleagues the general nature of the solutions to problems, but you may not copy all or any part of a program or a solution to a problem from another person.

Homeworks

There will be one homework approximately every two weeks, and you will have approximately two weeks to work on them. You must submit your homeworks electronically using the submit program. No homeworks will be accepted via e-mail or on paper. Assignments can be handed in late but will be penalized with 10% per day. Homeworks should be submitted before 10:00 PM on the day they are due. No homeworks will be accepted two weeks after the deadline.

In order to use the submit program effectively, you must use the exact file names mentioned in each homework. Please follow the instructions carefully. Otherwise, you may not get credit for your homework.

You can get partial credit for an incomplete program, but you will have to demonstrate that it solves some sub-cases of the problem. Even if your program does not produce completely correct output, submit the code, a compilation and any test runs as part of the script you normally would submit.

Compiling

Although you may work on your programs on other machines, the final versions that you submit must run on our CSA network. We suggest that you do not wait until the last minute to run your program on our system.

Since this course teaches programming in C, we expect your code to conform to the rules for ANSI C (i.e., Standard C). This means you cannot use things from traditional (K&R) C, C++, or special features our compiler gives you.

To enforce this, you must compile all your program with:

gcc -ansi -pedantic -Wall sourcecode-files

The "-ansi -pedantic" tells the compiler to be real strict (pedantic) about following ANSI rules. The extra "-Wall" makes the compiler gives additional useful warnings (e.g., for things like unused variables).

Documentation and Style

The documentation of a program is as important as the program itself. Good documentation is essential to make the program understandable to other humans. Documentation will carry a good percentage of the grade for programs. There are several aspects to consider when documenting a program, and they are discussed below. You must follow the documentation instructions and conventions carefully.

Each file submitted should contain a header with the following information:

  1. File name,
  2. Your name,
  3. Your login name,
  4. Your BU ID number,
  5. Assignment and problem numbers,
  6. Date.

For example, if I wanted to submit a file called "myfile.c" then the beginning of that source code file should read:

/*
 * File name: myfile.c
 * Name: Steve Homer
 * Login name: homer
 * BUID: U123456789
 * Assignment: 2
 * Problem: 1
 * Date: Jan 1, 1999
 */

Comments

Comments are a very important part of a program's documentation. They should help other people (e.g., the grader) understand your code. Each part of a program (e.g., a module) must be documented. The following are some general guidelines that you must follow:

  1. Header (.h) files.

  2. Source (.c) files.

    Source files must also contain a description of what the code contained in them does. You should describe what the problem being solved is and your method of solving that problem. You should also describe any known bugs, cases not handled by the code, etc. This description must be included at the beginning of the file, right after the header with your name.

Names for variables, types and functions

The names that you assign to variables, functions and types can easily be self-documenting. I.e., a variable with a well-chosen name will need very little commenting to make its use understandable.

Starting from Homework 2 you must use the following conventions when naming variables, types and functions:

  1. Function names will start with a capital letter. For example, int Fibonacci(int);
  2. Variable names start with a lower case letter. The name of pointers should end with a "P" (capital p).
  3. Type names begin with a lower case letter, and end with a "T" (capital t).
  4. Constant names must be all capital letters. For example, #define MAX_SIZE 10

As mentioned above, we will give you the names of the files you must submit.

Indentation

Proper indentation is important in helping others, and yourself, to understand code. Here are some examples:
if (Exp) {
  statement1
} else {
  statement2
}

for (Exp1; Exp2; Exp3) {
  statements
}

There is more than one common way to align the beginning "{" and ending "}" braces for a block of code. We suggest you use the one demonstrated above.

Some text editors, Emacs for example, let you perform indentation automatically. This is also true of some PC editors. Using color-coded C code can also help you with syntax errors.


Originally version by Alberto Oliart / Edited by Stever Homer and Rob Pitts