Robustness: Your primary task is to create a working, robust program. This means that your program should produce correct answers on all legal input and produce comprehensible error messages on invalid input. Keep in mind that (unless otherwise mentioned) unreasonably long running time is probably an error. How should you ensure robustness? Well, at the least, try to complete without problems all of the following four Unpatented Steps to Robust Code^TM in succession on a Linux ugrad.cs.ubc.ca servers (like lulu.ugrad.cs.ubc.ca) before submitting your code:

• Compile without warnings or errors with g++'s -Wall flag enabled. (Notify us of errors in our code.)
• Run correctly on all test data we give you. (Tell us if you find our test data in error!)
• Run correctly on test data of your own which has:
  • difficult cases
  • boundary cases (both sides)
  • minorly and egregiously incorrect input
  • the empty file
• Run correctly on the test data of another group. This is an exception to the collaboration policy allowing you to take a record from an interaction. You must credit this group in your README.

Coding clearly: You should always make an effort to write code that is easy for other people to read. In the real world, this is an important skill that is valued higher than cleverness or using the least number of lines/characters possible. In this class, it is important so that we can understand your program and grade it fairly. By reading through your code and comments, we should be able to figure out how your code is organized and why it works. If we can't, we reserve the right to deduct marks.

Commenting: One aspect of writing clear code involves commenting your code so that it is clear what it does without reading it line by line (have mercy!). Comments should be used: (a) at the top of each file to tell what code it contains, (b) at the top of each function to tell what it does, (c) at the declaration point of important variables, (d) on any lines whose purpose is non-obvious, and.. (e) everywhere else they should be used.

Coding simply: Although C and C++ allow it, there is no benefit to writing overly complicated statements such as:

    if ((i = myfunc(counter++)) < num_iterations) {
       ...
    }

when they could easily be rewritten in a clearer manner:

    i = myfunc(counter);
    counter++;
    if (i < num_iterations) {
      ...
    }

Coding should not be a macho activity. It should be like writing English sentences that you truly want someone to understand (including "future you" who may need to come back and reread this stuff).

Speed: As long as your program takes a reasonable amount of time, we will neither dock points nor give bonus points on the basis of speed. In other words, all of your data structures should have the expected asymptotic time and space complexity, but the constants will not generally matter. Robustness and clarity come first! If you're curious about how to make programs run blazingly fast, talk to us, and we'll give you some tips and tools. (Here's a freebie: never optimize any piece of code until you've tested your program's speed and discovered that that code is a bottleneck. Here's another: use a profiling tool like gprof to find and improve your bottlenecks; don't just guess where they are!)

Working Individually vs. with Partners: All of the programming projects this term will be designed to be completed in groups, normally of two. If you choose to work on a programming assignment individually, you may still collaborate as described in the course syllabus (cite the individuals you work with in your README). However, we expect that all of these assignments will be easier completed in groups!

Ideally, we view group work as a way for people with complementary skills to tackle the problem together in order to learn more effectively and to deal with difficulties in the development process, bugs in their code, or problems with UNIX/g++. Two heads are often better than one in these situations! Our expectation is that all group members will work on the program together rather than dividing the program into parts and sewing the parts together the day before the project is due.. but you are allowed to do this (strongly discouraged but allowed). For those of you who decide to work in a group, here is what we expect of you:

• Groups turn in a single programming project that is the result of their combined efforts. Groups receive the identical grade on the programming assignment except in extreme circumstances.

• Groups indicate all members (with student IDs and ugrad logins) and describe their division of labor in the README.

• All group members understand the entirety of the code, and questions pertaining to the projects may be assigned on the homeworks or on the midterm/final exams to ensure this.

• Groups working in a public lab are careful not to disturb others in the lab.

We firmly believe in the value of collaboration. The above rules are intended to ensure that all group members learn from the work. If you have any questions or problems with these policies, let us know (but do NOT violate them) or simply work by yourself.

Handin procedures:

Your Makefile may support handin directly. Read the assignment documentation for more info.

Programming projects will be submitted electronically using the handin tool by 9PM on the project due date. Late work will not be accepted. Only one group member should handin the code! We may be flexible with due dates if you contact us well in advance of the original due date.

Include all code files and header files required to compile and run your project in your submission. Also, include any other files (such as sample input) necessary for correctly running your program. Among these should be a makefile which will correctly compile and link your code when the command "make" is executed! Do not send executables, or sample output. Finally, of course, include a README which describes your submission.

Generally, the contents of the README will be described on the assignment writeup, but here are items that should always be included:

• your name (or the group's and all members' if you're working in a group), student ID, ugrad login, and project number
• a brief (1 short paragraph) description of your project: what ADTs/algorithms you used, any bugs or features that are not working as well as they should (better to admit to them than have us discover them), any design decisions you made, or unique aspects of your code (especially anything above and beyond what was assigned)
• a brief description of the files in the submission which you created or changed. For example:
  main.cpp - our main C++ file for the program
  list.cpp - our list ADT implementation
  list.h - our list header file
  hash.cpp - Koffman and Wolfgang's hash table implementation with our changes
  input/input1.txt - Sample input that shows our program works
  input/input2.txt - Malformed sample input that shows our program handles errors etc.

To use handin, place all the files to be submitted in the directory whose name is:

~/cs221/NAME

where NAME is the name of the assignment (e.g., assign1, proj1, assign2, ...).

For instance, to submit proj2, student r2d2 would first (if necessary) create a directory called cs221 in her.. his.. its home directory by typing the following commands at the prompt in the Xterm window from its home directory:

mkdir cs221

It would then create the proj2 subdirectory by typing the commands

cd cs221 ; mkdir proj2

After placing the files containing its solutions for proj2 in the directory

~/cs221/proj2

created in the previous steps, r2d2 would then run the handin command while in its home directory:

handin cs221 proj2

After you have submitted your assignment, always verify that the handin was successful using the -c option to handin.

handin -c cs221 proj2

If you want to overwrite an already submitted copy of your assignment, you can do it using the -o option:

handin -o cs221 proj2

You can use the -o option as many times as you like. Submit your work well in advance of the deadline, even if it is not yet finished, and then overwrite the submission regularly until you are ready to handin the final copy. This will prevent you from getting in trouble if your computer or the network connection dies right before you submit your assignment. Note that you can not overwrite your submission after the deadline has passed.

Handing in from home?

Did you know that you can access your lab account from your own computer? Simply install XManager. You'll be able to use Xshell like a UNIX terminal in the lab, and Xftp to transfer files. If you're having trouble figuring out how to do this, use the discussion board or contact the staff.

You may also wish to try Web Handin. But.. does your code work properly on lulu.ugrad.cs.ubc.ca? Web Handin also tends to mess up directory structures, so we would prefer you to use XManager.