Homework Policies

See also the homework grading page for information on grading.

Email and Mailing lists

Announcements will be distributed using the mailing list cs-70-l@hmc.edu. It is your responsibility to confirm that you are on this list. (If you don't know how to do this, send mail containing the single word "help" to listkeeper@hmc.edu.)

Homework grades and the like will be mailed to your Turing account. It is your responsibility to check your Turing mailbox regularly. If you typically read your mail on some other machine, we strongly advise you to put a .forward file in your Turing account, so that mail will be forwarded to your usual mailbox.

General Submission rules

All homework must be submitted on Turing using the cs70submit or cs70submitallprogram. You may develop your code on any system you choose, but we will be testing it on Turing using the g++ compiler, and it is your responsibility to ensure that it will run on that computer using g++ -Wall -pedantic. Each assignment will require you to submit two or more files with specified names. One of these files will always be named README, and will contain the English-language documentation for the program. The other file(s) will contain the program itself. The README file will usually have a later deadline than the other files.

Unless otherwise specified, you must use the filenames specified in the assignment, or points will be deducted from your grade. The only variation allowed is in file extensions: although the assignments will specify the .cc extension (e.g., median.cc), we will allow any extension accepted by g++ (i.e., .cc, .C, .cxx .cpp, or .c++).

Frequent Submissions

To paraphrase the late Mayor Richard Daley of Chicago, submit early and often. Every time you reach a milestone (header files completed, code written, code compiles, something starts working even a little bit, etc.) or take a break, run cs70submitall to submit what you have so far. Doing so has several advantages:

• If the system crashes, you won't have lost everything.
• If you really break your program later, you can easily demonstrate that it used to work.
• If you come to us for help, we can look at earlier versions of your program to find out what went wrong.
• If you get sick or have an emergency, you will be able to convince us that you didn't just put things off until the last minute, and you will thus have a much easier time getting an extension.

Late Submissions

Late submissions will be penalized severely; see the homework grading page for more information. A submission that is even one second past the deadline, by Turing's clock, is considered late. We will make appropriate arrangements for extended or last-minute system crashes, bugs in assignments, vague or broken specifications, or other factors beyond everyone's control. Your responsibility is to inform the course staff promptly if you detect or suspect such a problem. If a problem emerges at the last minute so that we cannot correct it, clearly describe in your documentation the problem you encountered and what assumptions you made to work around it.

Grading

Full homework grading guidelines can be found on the homework grading Web page.

All of your submissions will be graded electronically. The graders will insert commentary into your programs and README files regarding good and bad aspects, errors found, things that don't work, etc. When grading is complete, the graded files will be e-mailed back to your Turing accounts. You will be able to find the grader's comments and the scoring by searching for the string "//#" (without the quotes. This string will be used to mark all of the grader's changes to your files.

If you have questions about the grading, please try to talk to the graders themselves first. If they cannot resolve your difficulty, feel free to ask your professor about the problem.

Commenting and Documenting Code

Code must be properly commented. The main idea is that the grader should be able to understand your code easily, not have to tear his hair out wondering what some statement is doing. The first time you have to deal with poorly commented code (if you haven't already), you will understand how annoying it is.

In particular, the top of each code file should contain your name, the course and assignment numbers, a brief summary of what's in the file, and any non-obvious details about how to compile and run the code. This might typically be 10-30 lines of text.

Line-by-line comments should be included as necessary to make the code easy to read. A clear coding style, together with informative variable and function names, will reduce the number of comments required. Obscure code or cryptic function names will cause loss of points (for bad style) and also require more extensive comments. We reserve the right to grade excessively impenetrable code as if it did not work.

The README file

The README file is one of the most important parts of the assignment. Its purpose is to document your program. The README file must be in plain ASCII text (not HTML or MS-Word format), and in it you must specify:

• Your name.
• The homework number.
• The purpose of your program (i.e., the problem statement). Usually, this will be a paraphrased version of the homework specifications. (Direct copying is OK, if the specification is reasonably short, such as one or two paragraphs, but you must give proper attribution.) Be sure not to confuse the purpose of the program with the purpose of the assignment. This section should describe what your program can be used for.
• The format of the input and output.
• Any special restrictions, bugs, or limitations (size of input, behavior with malformed input, etc.).
• How the program achieves its result:
  • Algorithm.
  • Data structures.
  • General structure of the program.
  • Files in the program.
• Solutions to any non-programming problems.

The description of how your code works will probably be brief (a few sentences) for the early assignments and get longer (e.g. several paragraphs) towards the end of the term. However, the descriptions must always be complete. The "general structure" section should describe the main functions and what they do, the key steps in the algorithm, and how your code is organized into functions.

The "files" section may be omitted if the program is contained in a single file. Otherwise, it should briefly explain how the program is organized into files. Files that "go together" (such as hh and cc files) should be discussed as a group. The purpose of this section is to help the reader locate various classes and functions, so the descriptions can usually be quite brief.

The documentation should not contain more than very brief fragments of code or pseudocode. Concentrate on explaining the main features of the algorithm, as if to someone working on another system in another programming language.

Sometimes, students ask whether some particular item should be included in the README file. The general rule is, "if you're unsure, put it in." The graders do not normally deduct points for having excessive material in the README, but being too brief will often cost you.

To help you understand what a good README looks like, here are three sample files. All of the samples have been taken from the same homework assignment. All three earned top grades and illustrate different ways to approach writing a README. The first is very extensive. The second is shorter but still thorough and well organized (although the grader would have preferred to see some section headers). The last is less than a quarter the size of the first, yet still covers all the bases. It is a good example of how terseness can be sufficient.

The README Deadline

Note that the deadline for submitting the README file is later than the deadline for the code. This is to encourage you to spend extra time on documentation, rather than spending your last few minutes frantically trying to fix bugs.

English Usage

The README file should be written in your best English, using correct spelling and grammar. Do not write in all uppercase or all lowercase, both of which seriously harm readability. Write in complete sentences using proper punctuation.

One excellent way to be sure that your README file uses good English is to run it by the writing center.

Things to watch out for:

• Use a spelling checker to help eliminate typos, and try to be aware of homonyms and use them correctly. We will be relatively lenient about misused homonyms, but we will deduct points for any misspelling that would have been flagged by a spelling checker.
• Make sure you use apostrophes correctly: an apostrophe means ownership, not plural, except that pronouns don't ever take apostrophes (i.e., we say that John lost "his" textbook, not "hi's"; similarly for "hers" and "its"). As for contractions, if you have trouble with them, just avoid them. If you write "it is" you may sound somewhat stuffy but you won't misspell "it's".
• Use sufficient whitespace. In particular, leave a blank line between paragraphs.
• Don't overuse itemization. Organize your documentation into paragraphs.
• Avoid paragraphs shorter than three sentences, or longer than ten.
• When naming functions, be consistent about your use of parentheses. If you prefer writing "make_list" to "make_list()" or vice versa, stick to that style throughout the README.
• The README file should describe the code as it is. It should not be a story about how you constructed the code.

Some allowances will be made for special writing difficulties, such as dyslexia or English as a second language, but only if we are informed beforehand.

Coding style

Make every effort to produce a readable program. See the C++ style hints for some general tips.

© 2001, Geoff Kuenning

This page is maintained by Geoff Kuenning.