MS2: Code Quality, Documentation, and Testing Rubric

Code Quality [6 points]

Spot check: Select two .ml files at random, excluding test files. From each file, read about 100 lines starting from a random location in the file. Evaluate those 200 total lines against the following rubric.* Apply each deduction at most once.

• -0.5: Line longer than 80 characters
• -0.5: Identifier names not either short and idiomatic, or longer and self-documenting
• -0.5: Identifiers do not use correct and consistent case (camel vs. snake)
• -0.5: Indentation needs improvement
• -0.5: Code too sparse or too dense; whitespace needs improvement
• -0.5: Overuse of parentheses
• -0.5: Overly long functions (usually should be at most 10-20 lines)
• -0.5: If expressions can be simplified with Boolean operators
• -0.5: If/match expressions nested more than 2 levels deep
• -0.5: Function application nested more than 4 levels deep
• -0.5: Reimplemented library function

* Evaluating a 1500 line codebase would be beyond the time commitment that graders can provide. Instead, graders are spot-checking: randomly sampling a part of your code that is similar in size to earlier programming assignments, and assessing just that part in detail. So, you need to make sure that all parts of the codebase are in good shape, because you can’t predict what will be sampled.

Documentation [4 points]

Run make docs and examine the resulting HTML. If the team provided both public and private documentation, read only the public. Exclude any test modules.

• -4: make docs does not work.
• -1: A module is missing specifications for two or more functions.*
• -0.5: The generated index is missing a description for a module.

* May be applied multiple times. If just one function in a module is missing a spec, let it slide.

Test Plan [4 points]

The test plan should be located in a comment at the top of the test file.

• -4: The test plan is missing.
• -1: The test plan does not explain which parts of the system were automatically tested by OUnit vs. manually tested.
• -1: The test plan does not explain what modules were tested by OUnit and how test cases were developed (black box, glass box, randomized, etc.).
• -1: The test plan does not provide an argument for why the testing approach demonstrates the correctness of the system.

Test Suite [6 points]

The test suite should be runnable with make test.

• -3: The OUnit suite does not have at least 50 passing tests.*
• -5: The OUnit suite does not run with make test, or dies in the middle of running.
• -6: There is no OUnit suite.

* On A2 this semester, the course staff test suite contained 52 tests. That was the smallest test suite out of all the assignments. Students wrote a median of 200 LoC (including tests) to solve the assignment. For a project in which 500 LoC/person is expected, 50 passing tests therefore is a minimal amount. In reality we should probably be asking for more.