General Advice on Programming Assignments

You are allowed and encouraged to discuss various aspects of this assignment with your classmates. However, the overall design and final details and implementation must be your own.

Coding style

Use a reasonable organization for your overall program:

Design a fairly reasonable class structure. On the one hand, don't stick everything into one class/struct. On the other hand, don't be bureaucratic and require the reader to follow one class definition after another to find a single line of code wrapped in n layers of methods, with each method doing nothing but calling the next one. If the way you design your code feels sloppy to you, it probably is. Utilize multiple files in a way that is consistent with the general use of C/C++. Don't use more files than necessary, you don't have to put each class/struct in a separate file of its own (this is not Java).

Don't use literals!

Use either const, enum, or #define to give your literals meaningful names.
#define ONE 1
const ZERO=0;
would be examples of names that are no different than using literals and would be treated as equivalent to using literals. We do deduct points for each occurrence of literals or equivalently literal names, even if it is the same one. The only exceptions will be for loop counter, command-line options, NULL(0), TRUE/FALSE(1/0) testing/setting, help and error messages printed out to user, and mathematically well-defined uses such as (1-probability) or (1-interpolating_factor) or to test for negativite values (< 0), etc. The intent here is to ensure that should the literal value need to be changed in the future, it only needs to be changed in one place. Thus defining '0' as "ZERO" does not serve this purpose because should the value '0' need to be changed in the future, the macro "ZERO" becomes totally misleading. We will thus deduct points for such semantically meaningless names also.

Use reasonable comments:

Explain what each class does and what each data member is used for. A one or two line description of most member functions is also desirable. Where you use non-standard coding techniques, document them. List your name and the date last modified for each file.

 

Remember that a useless comment is worse than no comment at all.
int temp; // declare temp. variable
would be an example of a useless comment which just makes code harder to read!

Use reasonable formatting:

From indentation alone, it should be obvious where a given code block ends. Avoid lines that wrap in an 80 column display wherever possible. Your code should be tight, compact, and visually tidy. Don't let bits and pieces fly off every which way. Your code is not abstract painting.

Variable names:

Use reasonable and informative variable names, but limit name size to a reasonable length. A 40-character name better has a very good reason to exist. Variable names like 'i' and 'j' can be reasonable, but you should not use such variables to store meaningful long-term data. Other than LCV (loop control variables) you should use descriptive names for your variables, functions, classes, methods, structures, etc.

Reduce, Reuse, and Recycle your code, algorithms, and structures:

Try using inheritance, templating, polymorphism (virtual function), or similar methods to reduce the size of your code. Do not unnecessarily duplicate code. Less code leads to fewer places for bugs to hide in and less debugging for you. If you find yourself rewriting basically the same code more than once, stop and try to see if you can somehow reuse the code by making it a function call or implementing a polymorphic function.

Unreadable code can cost you up to 10 points!

Empirical efficiency

We will check for empirical efficiency both by measuring the memory usage and running time of your code and by reading the code. We will focus on whether you use unnecessary temporary variables, whether you copy data when a simply reference to it will do, whether you use an O(n) algorithm or an O(n^2) algorithm, but not whether you use printf's or fprintf's. Nor whether your ADTs have the cleanest interfaces. In general, if the tradeoff is between illegible and fast code vs. pleasant to read code that is unnoticeably less efficient, we will prefer the latter. (Of course pleasant to read code that is also efficient would be best.) However, take heed what you put in your code. You should be able to account for every class, method, function, statement, down to every character you put in your code. Why is it there? Is it necessary to be there? Can you do without? Perfection is reached not when there is nothing more to add, but when there is nothing more that can be taken away, someone once said.

Hints and advice

• Design your data structures and work through algorithms on paper first. Draw pictures. Consider different possibilities before you start coding. If you're having problems at the design stage, come to office hours. After you have done some design and have a general understanding of the assignment, re-read this document. Consult it often during your assignment's development to ensure that all of your code is in compliance with the specification.
• Always think through your data structures and algorithms before you code them. It is important that you use efficient algorithms in this programming assignment and in this course, and coding before thinking often results in inefficient algorithms.
• You shouldn't print to stderr/cerr unless there is an error or a diagnostic message.
• Make sure you don't clutter stdout/cout with unnecessary output. Do remove all printf()'s or cout's you've added for debugging purposes. You should debug using a debugger, not with printf()'s. If we can't understand the output of your code, you will get zero point.
• The teaching staff will be happy to help you track down bugs, but you have to fix them yourself once they are found. We will not help you track down a bug unless you can show us in gdb where you suspect the bug to be. That is, you need to show us that you have tried your best to track down the bug, and that you have used gdb.

  To encourage early start on the assignment, we will stop helping you to debug 48 hours before the due date. For a Thursday 10:00 pm deadline, we stop helping you at 10:00 pm on the Tuesday prior.

Testing Your Code

We will be grading for correctness primarily by running your program on a number of test cases. If you have a single silly bug that causes most of the test cases to fail, you will get a very low score on that part of the programming assignment even though you completed 95% of the work. Most of your grade will come from correctness testing. Therefore, it is imperative that you test your code thoroughly. Each testcase should test only one particular feature of your program.

Have fun coding!