I'm collecting a list of possible items for grading rubric for a coding assignment. Below is a start. Is this complete, or am I missing important criteria? I welcome other ideas.

  • Effectiveness
    • Runs without errors
    • Passes all unit tests
    • Handles all typical cases
    • Handles common edge cases
  • Elegance
    • Uses language idioms
    • Selects correct data structures
    • Select correct built-in functions
    • Uses packages appropriately
    • No unnecessarily repeated work
    • No unnecessary hard coding
    • Can scale well with potentially large inputs
  • Readability
    • Clear, semantic naming
    • A single lines only contains a single idea
    • No unnecessary variables
    • Style always follows conventions
    • Consistent formatting/indentation
  • Documentation
    • All modules have a docstring
    • All functions have a docstring
    • Each line has a comment
    • All documentation are meaningful and complete thoughts
    • All documentation are formatted consistently according style guidelines
  • $\begingroup$ Are you looking for more criteria? Or scoring guidelines? $\endgroup$ – Ben I. Aug 17 '20 at 19:23
  • $\begingroup$ I'm looking for more criteria. $\endgroup$ – Brian Spiering Aug 17 '20 at 21:25
  • $\begingroup$ Okay, I edited your question to include the ask :) $\endgroup$ – Ben I. Aug 18 '20 at 18:58
  • 4
    $\begingroup$ Few lines should need a comment. If they do, both are probably wrong. $\endgroup$ – vonbrand Aug 22 '20 at 2:27
  • 1
    $\begingroup$ There are 4 types of comment: To say why, to augment a weakness in the language, to augment a weakness in the programmer, noise. $\endgroup$ – ctrl-alt-delor Sep 22 '20 at 21:13

So, if I were reading code, I would object if someone submitted code with every line commented. I am not aware of any professional code that does this, and when I occasionally receive code from students where this is done, it is simply cluttered. I believe that the real criteria here is clarity. Excellent variable naming will often accomplish this sans comments.


if ( maxSoFar < currentValue )


if ( maxSoFar < currentValue ) // Find out if the maximum is less than the current value

Truly, the comment adds nothing to the code here. As a practical matter, it has been my experience that over-commenting makes my students work difficult to grade by reducing the clarity.

Unrelatedly, a missing criterion is having a run-time appropriate to the desired algorithm.

As a practical matter, you may find this rubric difficult to grade with. You will need to give careful attention to weights, and to how those weights will actually be evaluated. (e.g. in a 3-point category, what sort of work would grant 3 points, what would grant 2 points, and what would grant 1 point?)

  • 2
    $\begingroup$ If the comments disagree with the code then they are both wrong. (quote from someone, but I don't remember who) Dijkstra-ish, anyway. $\endgroup$ – Buffy Sep 22 '20 at 0:10
  • 1
    $\begingroup$ @Buffy Then I'm lucky they agree! Though my chosen example is a bad one, because my comment is adding information that would only be otherwise apparent within the following code block. I will change it. $\endgroup$ – Ben I. Sep 22 '20 at 3:12
  • 1
    $\begingroup$ @Buffy It's cleaned up now, and makes me want to throw up just an eensy-weensy bit more than it did a few minutes ago. Nice! $\endgroup$ – Ben I. Sep 22 '20 at 3:14

First, there are a couple of things on the list that are wrong. Ben I. has covered one of them. Comments on every line are a "code smell". If the code itself isn't obvious from its naming and structure then it is broken.

But lots of comments in the code indicate another fault. The methods/functions you are writing are too long and too complex to understand. Unfortunately, a lot of people, not just students, write code that they can't understand. If your methods are more than a few lines long or your structured statements are nested deeply (more than 3) then your code is nearly impossible to understand.

I suggest that you learn about Cyclomatic Complexity as it applies to programming. I get itchy when my code has complexity > 3 and find it impossible when it reaches 7. (Even though the recommendation is to break it down at 10 - ugh). Related to this is The magic number seven, which explains why complex things are hard/impossible to understand.

I would also object to the "no unnecessary variables" rubric. Of course, it depends on what you mean by unnecessary. Often, by introducing a variable (and giving it an intention revealing name you can often improve its clarity by making the intent obvious. (Whoa, I haven't linked to Ward's original wiki in a long time. Ward Cunningham invented the wiki, BTW.) I will often, for example, create a named variable to use as an argument to a function rather than just passing the expression defining the variable. This makes it much clearer.

Don't imagine that such "extra variables" make the code less efficient. Any decent compiler will notice the limited lifetime of such variables and optimize them away. And, of course - Ward again - "Premature optimization is the root of all evil" - Knuth.

I could quibble a bit more, but those two points are important. If the code is clear it can be extended or fixed. If it isn't then you are in deep trouble.

Caveats. Of course, the above depends on the language you use. If you write assembly language it is impossible to reveal intent other than with comments, so you need a lot of them. Maybe even one per line in some (not all) cases. If you write in a language that doesn't let you declare a variable at the point of first use then it is harder to justify those extra variables that have to be declared long before they have a "meaning" in the code.

One reason that I recommend Eclipse as the development environment is that it has lots of features to make "nice" code. It will factor out methods to reduce complexity, for example. It has a plug-in to show you the complexity. It is much more than a text editor since what it shows you in the "text" window is actually a rendering of the parse tree. It will also reformat the code to fit the desired convention.

  • 2
    $\begingroup$ Agree, except: if you are declaring variable long before they are used (because your language makes you declare them at the top of the method), then your methods are too long. $\endgroup$ – ctrl-alt-delor Sep 22 '20 at 21:19

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.