<p>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.</p>
<p>Consider:</p>
<pre><code>if ( maxSoFar &lt; currentValue )
</code></pre>
<p>vs</p>
<pre><code>if ( maxSoFar &lt; currentValue ) // Find out if the maximum is less than the current value
</code></pre>
<p>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.</p>
<p>Unrelatedly, a missing criterion is having a run-time appropriate to the desired algorithm.</p>
<p>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?)</p>

CC BY-SA 4.0
2020-09-22T00:10:44.183Z
If the comments disagree with the code then they are both wrong. (quote from someone, but I don't remember who) Dijkstra-ish, anyway.
Buffy
CC BY-SA 4.0
2020-09-22T03:12:51.310Z
@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.
Ben I.
CC BY-SA 4.0
2020-09-22T03:14:16.253Z
@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!
Ben I.
CC BY-SA 4.0
2020-08-22T13:38:50.690Z
2020-09-22T03:13:32.233Z
2020-09-22T03:13:32.233Z
Ben I.
<p>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 &quot;code smell&quot;. If the code itself isn't obvious from its naming and structure then it is broken.</p>
<p>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.</p>
<p>I suggest that you learn about <a href="https://en.wikipedia.org/wiki/Cyclomatic_complexity" rel="nofollow noreferrer">Cyclomatic Complexity</a> as it applies to programming. I get itchy when my code has complexity &gt; 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 <a href="https://en.wikipedia.org/wiki/The_Magical_Number_Seven%2C_Plus_or_Minus_Two" rel="nofollow noreferrer">The magic number seven</a>, which explains why complex things are hard/impossible to understand.</p>
<p>I would also object to the &quot;no unnecessary variables&quot; rubric. Of course, it depends on what you mean by unnecessary. Often, by introducing a variable (and giving it an <a href="http://wiki.c2.com/?IntentionRevealingNames" rel="nofollow noreferrer">intention revealing name</a> 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.</p>
<p>Don't imagine that such &quot;extra variables&quot; 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 - <a href="http://wiki.c2.com/?PrematureOptimization=" rel="nofollow noreferrer">&quot;Premature optimization is the root of all evil&quot; - Knuth</a>.</p>
<p>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.</p>
<hr />
<p>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 &quot;meaning&quot; in the code.</p>
<hr />
<p>One reason that I recommend Eclipse as the development environment is that it has lots of features to make &quot;nice&quot; 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 &quot;text&quot; window is actually a rendering of the parse tree. It will also reformat the code to fit the desired convention.</p>

CC BY-SA 4.0
2020-09-22T21:19:13.397Z
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.
ctrl-alt-delor
CC BY-SA 4.0
2020-09-22T13:01:27.407Z
2021-06-02T10:43:46.350Z
2021-06-02T10:43:46.350Z
Buffy
<p>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.</p>
<ul>
<li>Effectiveness
<ul>
<li>Runs without errors</li>
<li>Passes all unit tests</li>
<li>Handles all typical cases</li>
<li>Handles common edge cases</li>
</ul>
</li>
<li>Elegance
<ul>
<li>Uses language idioms</li>
<li>Selects correct data structures</li>
<li>Select correct built-in functions</li>
<li>Uses packages appropriately</li>
<li>No unnecessarily repeated work</li>
<li>No unnecessary hard coding</li>
<li>Can scale well with potentially large inputs</li>
</ul>
</li>
<li>Readability
<ul>
<li>Clear, semantic naming</li>
<li>A single lines only contains a single idea</li>
<li>No unnecessary variables</li>
<li>Style always follows conventions</li>
<li>Consistent formatting/indentation</li>
</ul>
</li>
<li>Documentation
<ul>
<li>All modules have a docstring</li>
<li>All functions have a docstring</li>
<li>Each line has a comment</li>
<li>All documentation are meaningful and complete thoughts</li>
<li>All documentation are formatted consistently according style guidelines</li>
</ul>
</li>
</ul>

CC BY-SA 4.0
2020-08-17T19:23:23.203Z
Are you looking for more criteria? Or scoring guidelines?
Ben I.
CC BY-SA 4.0
2020-08-17T21:25:32.597Z
I'm looking for more criteria.
Brian Spiering
CC BY-SA 4.0
2020-08-18T18:58:40.923Z
Okay, I edited your question to include the ask :)
Ben I.
CC BY-SA 4.0
2020-08-22T02:27:32.997Z
Few lines should need a comment. If they do, both are probably wrong.
vonbrand
CC BY-SA 4.0
2020-08-30T12:05:05.270Z
Since you have "Passes all unit tests", I guess "test coverage" is an implied criterium. Presumably, more unit tests are better, but only if they cover different cases.
Llewellyn
CC BY-SA 4.0
2020-09-22T16:34:35.153Z
Scaling is pretty hard to judge. And for a "coding" assignment, rather than for an advanced concepts course, probably inappropriate. Likewise, too many criteria makes it harder to implement. Keep it simple.
Buffy
CC BY-SA 4.0
2020-09-22T21:13:47.247Z
There are 4 types of comment: To say why, to augment a weakness in the language, to augment a weakness in the programmer, noise.
ctrl-alt-delor
CC BY-SA 4.0
2021-05-17T14:48:59.770Z
I'm not too bad at adding comments but find it is much better to use appropriately named variables and additional variables for greater clarity which the proposer may suggest are unnecessary. What I am poor at is updating comments when refactoring which as has been pointed out renders the program wrong! However, great post and wonder if, Brian, you've got a final rubric.
WattCommunity
CC BY-SA 4.0
2021-05-19T01:09:25.657Z
@WattCommunity Welcome to cseducators!!  I converted your answer to a comment since it wasn't actually an answer to the question, but feel free to browse around and answer (or ask) questions!
Ben I.
<assessment>
Items on grading rubric for a coding assignment
# Items on grading rubric for a coding assignment

(Asked by: username_0 on 2020-08-17)

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

**Tags:** assessment

> **Comments:**
> **username_1**: Are you looking for more criteria? Or scoring guidelines?  
> **username_0**: I'm looking for more criteria.  
> **username_1**: Okay, I edited your question to include the ask :)  
> **username_2**: Few lines should need a comment. If they do, both are probably wrong.  
> **username_3**: Since you have "Passes all unit tests", I guess "test coverage" is an implied criterium. Presumably, more unit tests are better, but only if they cover different cases.  
> **username_4**: Scaling is pretty hard to judge. And for a "coding" assignment, rather than for an advanced concepts course, probably inappropriate. Likewise, too many criteria makes it harder to implement. Keep it simple.  
> **username_5**: There are 4 types of comment: To say why, to augment a weakness in the language, to augment a weakness in the programmer, noise.  
> **username_6**: I'm not too bad at adding comments but find it is much better to use appropriately named variables and additional variables for greater clarity which the proposer may suggest are unnecessary. What I am poor at is updating comments when refactoring which as has been pointed out renders the program wrong! However, great post and wonder if, Brian, you've got a final rubric.  
> **username_1**: @username_6 Welcome to cseducators!!  I converted your answer to a comment since it wasn't actually an answer to the question, but feel free to browse around and answer (or ask) questions!  

---

## 2 answers

### Answer by username_1 on 2020-08-22. Score: 5

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

> **Comments:**
> **username_4**: If the comments disagree with the code then they are both wrong. (quote from someone, but I don't remember who) Dijkstra-ish, anyway.  
> **username_1**: @username_4 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.  
> **username_1**: @username_4 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!  

---

### Answer by username_4 on 2020-09-22. Score: 5

First, there are a couple of things on the list that are wrong. username_1 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](https://en.wikipedia.org/wiki/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](https://en.wikipedia.org/wiki/The_Magical_Number_Seven%2C_Plus_or_Minus_Two), 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](http://wiki.c2.com/?IntentionRevealingNames) 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](http://wiki.c2.com/?PrematureOptimization=).

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.

> **Comments:**
> **username_5**: 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.  

---

