Student handbook

In contrast to the syllabus, which describes policies, this handbook is devoted to procedures. Please read both and follow the procedures carefully before asking the course staff for assistance.

This semester, the handbook is a work in progress. We will be adding to it throughout the course, so some topics may only appear in an outline or placeholder for now. If you are ever unsure of procedures after reading the relevant handouts, please ask on Ed.

Programming assignments

General policies

Submitted code must comply with our style guidelines. This includes formatting (which you should use IntelliJ to enforce), naming conventions, documentation, and the use of appropriate language constructs. Please refrain from using recent Java syntax features that have not been discussed in class (e.g., var, record, etc.); features present in Java 8 are usually fine (our textbook, and the Java Tutorials, do not go beyond this).

Regarding documentation, all types (interface and class declarations), methods, and fields must be given a specification as a JavaDoc comment (/** */), regardless of their visibility (this means private methods must be given a specification too). Exception: a class implementing an interface does not need to duplicate the interface’s specifications for its methods (but it should still document any refinements to the specification specific to that class). Implementation comments are up to your discretion, but if a TA ever asks “what are you trying to achieve with this code?”, that’s a sign you need more comments. Roughly one comment for every four lines of code should achieve a reasonable separation between the “what” (comments) and the “how” (code).

JUnit test methods do not need formal JavaDoc specifications, but the test case should still be described in English, ideally using a @DisplayName() annotation. Each JUnit test case should verify one facet of a class’s behavior, and the @Test annotation is required for every test method. A good template for describing test scenarios is “Given …, when …, then …”. For example, “Given an empty list, when an element is prepended, then the list’s size should become 1.” Multiple “then” clauses may be joined with “and”. Remember that only externally observable state should be mentioned in a test specification (so avoid talking about field values). Use JUnit assertions (not Java assert statements) to check any properties involved in a “should” clause (words like “must” or “will” are fine too). Prefer the most specific assertion function available (i.e., do not write assertTrue(x == 5) when you can write assertEquals(5, x), as the latter provides a better diagnostic message). Do not use mutable fields in test suites. Do not use JUnit assertions outside of your test suites.

Do not modify or extend the public interface of the given code. A theme of this course is interoperability—we should be able to mix together classes from several students and produce a working program, assuming that each class correctly implements its given spec. You may declare helper methods to assist when implementing a single class, but those methods must be private. (Unfortunately, this means you cannot write unit tests specifically for your helper methods; be sure to achieve coverage of your helpers though the tests you do write for the class’s public methods.)

Early assignments may require you to assert invariants and preconditions in constructors and public methods. Recall that this course implicitly assumes that fields and parameter values may not be null unless otherwise specified, so null values should be checked for in these assertions. The class invariant should be checked at the end of constructors and mutator methods. Exception: if checking a portion of an invariant or precondition would require more than O(1) work, then that check may be omitted if the assignment does not explicitly require it. Preconditions should be checked at the start of every constructor and every method that takes arguments. Ensure that Java assert statements are used for these checks, so that they will not contribute to a method’s asymptotic complexity when assertions are disabled.

Your submitted code should not print anything to System.out or System.err unless printing is documented as a side effect in the method spec. Typically this will only be done in main() or in helper methods used by main(). JUnit tests should not print any output. To be clear, printing variables is an extremely useful debugging technique that you are encouraged to employ during development. But any such prints must be removed when delivering production code.

Along similar lines, you should never call System.exit() except from main() (or from a helper method used exclusively by main()). Calling this function shuts down the entire JVM running the code, making your code non-composable. In practice, issues are most commonly seen when running tests (like our smoketester and autograder)—if you exit the testing program, then you will get no test results (and will be penalized as if all of those tests had failed).

Regrades and resubmissions

After an assignment has been graded, there will be a brief regrade window, typically about 1 week in duration, during which certain kinds of mistakes can be corrected. These mistakes include:

Rubric disputes

To report a grader mistake in the application of the rubric, please submit a regrade request on the CMSX assignment page. Be specific about which rubric items you are debating and why they do not apply to your code. Your grader will review your request and respond with a grading comment in CMSX. There is no penalty for submitting a regrade request.

Please do not submit a regrade request asking for the deduction associated with a rubric item to be changed—these are standardized across all students. Regrade requests should also not be used to challenge an autograder score unless you think there was a glitch in our test code or infrastructure. If you just have a question about why your code needs improvement, go ahead and ask on Ed Discussion, where more staff will be able to assist you.

Autograder reruns

If your submission did not compile or did not run, or if you lost a large number of points from the autograder due to a fundamental bug, then you may resubmit a fixed version of your submission and we will re-run the autograder on it. To resubmit to the autograder, upload your revised submission to the “A# resubmission” assignment on CMSX. Be sure to upload every file required for the assignment (not just the ones you revised). There is no need to open a regrade request in order for the autograder to be rerun. With the exception of A1, there is a 10 point penalty for resubmitting to the autograder. If, after this penalty, the autograder score of your resubmission is lower than your original score, then your original score will be kept.

The smoketester will be run on resubmissions, and you should pay careful attention to its feedback (in fact, heeding the smoketester is the best way to avoid the need to resubmit in the first place). The autograder will not be re-run until after the regrade window closes, so you may re-upload your resubmission as many times as you need to before then. There are no “second resubmissions” or regrade requests for re-run autograder results, so double-check that what you uploaded is what you intended to submit.

Manual grading of resubmissions

By default, only the autograder will be rerun on resubmissions; your manual grading score will remain the same. If you would like your grader to manually regrade your resubmission as well, this is allowed, but an additional 15 point penalty (25 points in total) will be assessed (except for A1). To request manual grading of a resubmission, follow the “autograder reruns” procedure above, then additionally open a regrade request on your original submission in CMSX saying that you would like to request manual grading of your resubmission.

For A1 (and A1 only), all resubmissions will be manually regraded as well for no penalty.

The deadline for regrade requests and resubmissions is firm—no slip days may be used to extend the deadline, and no requests or code submitted after the deadline will be considered. During the regrade window, your goal should be to address any major issues ASAP, learn from those mistakes, and then get back to working on the current assignment so you don’t fall behind.