Items on grading rubric for a coding assignment

Question

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

Answer 1

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.

Consider:

if ( maxSoFar < currentValue )

vs

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?)

Answer 2

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.