Programming Guidelines, CSE332 Summer 2012

Grading

For each project the, approximate and subject-to-change grade breakdown is:

Program correctness and Compilation:	40%
Architecture/Design, Style, Commenting, and Documentation:	30%
Writeup/README:	30%

The reason why "so few" points are allocated toward program correctness and error-free compilation is because CSE332 students are accomplished enough to know how to get their code to compile and run against the general input (although testing "boundary conditions" is a skill that students should aim for). Program correctness and error-free compilation is neither a fair nor discriminating measurement of project quality.

The two biggest discriminating factors among CSE332 students are program design (such as style and architecture) and analysis (the README/writeup), which is why these factors are heavily weighted. CSE332 is a course about data structures and the tradeoffs made during algorithm/data structure/abstraction design, so putting additional weight on program design, and questions about algorithm analysis and weighing tradeoffs, is more in keeping with the course goals.

Platform

You should use Java 7, making appropriate use of generics and JUnit. You may choose to work in a standard text editor or you may use an IDE. Course staff will do our best to support either the Eclipse or jGRASP IDEs. How you code is up to you. All the software you need for the course is available for free and is pre-installed on the machines in the department's undergraduate computing labs (Windows or Linux).

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 unreasonably long running time is probably an error (unless otherwise mentioned). How should you ensure robustness? At the very least, try to complete (without problems) the following steps before submitting your code:

• Compile without warnings or errors. (Notify us of any errors in the code we provide.)
• Run correctly on all test data we give you. (Tell us if you find an error in the provided test data. We are not infallible.)
• Run correctly on test data of your own which has:
  • Difficult cases
  • Boundary cases
  • Minorly incorrect input
  • Egregiously incorrect input
  • An empty input file
• Run correctly on test data from another student. The discussion board is a great place to share test data. If you use someone else's test data, you must credit this group in your writeup.

This doesn't guarantee robustness, but it's a good start! Turn in your test cases; they may help us grade your work better (read: give you the maximum possible amount of credit).

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 (or fails). If we cannot, we will likely deduct points.

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. Comments should be used:

• at the top of each file to tell what code it contains
• at the top of each method to tell what it does
• at the declaration point of important variables
• on or before any lines whose purpose is non-obvious.

Variable names: Variable names should conform with Java conventions (e.g., myVariableName, MyClassName, MY_CONSTANT_NAME) and should give a good idea of what purpose that variable serves in your program.

Coding simply: Although Java allows 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 involve grandstanding or distracting cleverness. It should be like writing English sentences that you truly want someone to understand, including yourself. Try to keep in mind the Three-Three Rule:
You should always write code such that you should be capable of understanding your code when reading it three months later at 3AM in the morning.

Speed

As long as your program takes a reasonable amount of time and your data structures and algorithms have the correct time and space complexity, we are not interested in small constant-factor differences. Robustness and clarity come first!

Using Java Class Libraries

Unless specifically approved or directed to, you should not use Java class libraries in your programming assignments to implement data structures and algorithms that are your responsibility. This rule is admittedly in contrast to many situations in the real world, but a large goal of this course is to fully understand core data structures that are so widely useful that Java provides them in its standard library. Often such understanding comes from implementing them yourself.