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:
- File name,
- Your name,
- Your login name,
- Your BU ID number,
- Assignment and problem numbers,
- 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:
- Header (
.h
) files.
- Header files must include, at the beginning of the file (after
the file header mentioned above), a statement indicating how to use the
header and/or the module it represents.
- Before each function prototype you must describe the function being
declared. To do this, describe the function inputs, its output, the
relationship between input and output, and any possible error conditions.
- Describe each constant or data type (structures, etc.) defined in
the header file.
- Source (
.c
) files.
- Each variable used in the code must be documented. Names of
variables and functions are also an important part of the documentation
(see below).
- Not every line of codes deserves a comment. You should document in detail
only those parts that are obscure or contain a non-obvious trick.
- When closing a block that belongs to another statement, the block
of an if statement for example, put a comment indicating which
block is being closed.
- Any function prototype that was not included in a header file must
be documented as described above in the Header files section.
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:
- Function names will start with a capital letter. For example,
int Fibonacci(int);
- Variable names start with a lower case letter. The name of pointers
should end with a "P" (capital p).
- Type names begin with a lower case letter, and end with a "T"
(capital t).
- 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