Writing Rubrics That Actually
Work for Code Assignments.

Most instructors pick up rubric design from the education literature, where rubrics were developed for essays and presentations. The same structure gets applied to code — and it mostly works, until it doesn't. Code has failure modes that prose doesn't. A program can pass every test and still be a maintenance nightmare. It can be beautifully structured and completely wrong. A rubric that doesn't account for this produces grades that confuse students instead of guiding them.

The four dimensions of code quality

Before writing criteria, it helps to separate what you're actually evaluating. Code assignments typically involve at least four distinct concerns:

• Correctness. Does the program produce the right output? Does it pass the test cases? Handle edge cases?
• Structure. Is the code organised in a way that's readable and maintainable? Are functions appropriately sized and named?
• Efficiency. Does the solution use an appropriate algorithm for the problem? Is there unnecessary work being done?
• Style. Does the code follow the conventions expected for the language? Are variable names meaningful? Is documentation present where needed?

These don't always move together. A student might nail correctness and efficiency while ignoring structure entirely. Your rubric needs to be explicit about which of these you care about — and how much — for this specific assignment.

Weight criteria based on the learning objective

A week-one assignment teaching basic conditionals should weight correctness heavily and style lightly. A senior-level architecture assignment has the opposite priority. The mistake many instructors make is applying a generic weight distribution to every assignment — 50% correctness, 25% structure, 25% style — regardless of what the assignment is actually trying to teach.

Ask yourself: if a student understands the concept but writes messy code, should they pass? For an intro assignment, probably yes. For a software engineering course, probably not. The rubric should encode that decision explicitly, not leave it to grader interpretation.

Make failure states concrete

The most common rubric problem is criteria that are too abstract to apply consistently. "Code is readable" is not a criterion — it's an outcome. A criterion is: "Functions are under 30 lines with descriptive names" or "Magic numbers are replaced with named constants." When criteria are concrete, grading is consistent and students know exactly what they need to do.

This matters even more for automated grading. An automated system can evaluate "handles null input without crashing" reliably. It cannot evaluate "code is well-organised" without further definition. The more precise your rubric, the more useful the feedback becomes — whether it comes from a human or a system.

Separate tests from rubric criteria

Test suites and rubric criteria do different things. Tests verify behaviour. Rubric criteria evaluate quality. A student can pass all tests with code that should still lose points — and that's fine, as long as the rubric makes the distinction clear.

In CodeSpell, test results and rubric scores are tracked separately. This lets instructors give students a clear breakdown: "You passed 8 of 8 tests, but lost 8 points on code structure." That's more useful than a single number, and it's more honest about what was actually evaluated.

Share the rubric before the assignment, not after

This one sounds obvious, but it's often skipped. Students who see the rubric before they start writing code can make deliberate decisions about where to spend their effort. Students who see it after submission treat the grade as opaque.

A rubric is a teaching tool as much as a grading tool. If it's well-written, sharing it upfront doesn't help students game the system — it helps them understand what quality code actually looks like for this problem, in this context, at this level of the curriculum. That's the whole point.