CS/DS 125 - Fall 2018: Grading Rubric

This document lays out common criteria used to grade CS/DS 125 programming assignments. Each criterion has a number of different levels of achievement, with a description of how a submission will attain that level and the number of points assigned for reaching it. Please email or ask me if you have any questions about this rubric.

Criteria

Program Specifications / Correctness

This is the most important criterion. A program must meet its specifications (whether from a textbook problem or as written in the assignment) and function correctly. This means that it behaves as desired, producing the correct output, for a variety of inputs. (In CS/DS 125, we will be lenient with regards to producing correct output for all inputs, as we may not always have the tools needed to accomplish that, yet.) This criterion includes the need to meet specifications by writing a program in a particular way or using a particular language feature, if such a thing is mentioned in the problem.

If a specification is ambiguous or unclear, you have two choices: You can either make a reasonable assumption about what is required, based on what makes the most sense to you, or you can ask the instructor. If you make an assumption about an ambiguous specification, you should mention that somewhere in a comment so that the reader/grader knows what you were thinking. Points may be taken off for poor assumptions, however.

Readability

Code needs to be readable to both you and a knowledgeable third party. This involves:

Using indentation consistently (e.g., every function's body is indented to the same level)
Adding whitespace (blank lines, spaces) where appropriate to help separate distinct parts of the code (e.g., space after commas in lists, blank lines between functions or between blocks of related lines within functions, etc.)
Giving variables meaningful names. Variables named A, B, and C or foo, bar, and baz give the reader no information whatsoever about their purpose or what information they may hold. Names like principal, maximum, and counter are much more useful. Loop variables are a common exception to this idea, and loop variables named i, j, etc. are okay.
Organizing the code well. Once we have learned about functions, code should be organized into functions so that blocks of code that need to be reused are contained within functions to enable that, and functions should have meaningful names. This is a concept that we will be learning about as we write more and more code in CS/DS 125, and so few points, if any, will be taken off for organization issues that we have not yet addressed in class.

Documentation

Code written to be readable (as above) is ideally "self-documenting" to some extent. The organization of the code and the naming of variables and functions should explain what the code does as much as possible. Additional documentation that is almost always needed, however.

In notebooks, the programming environment of CS/DS 125, documentation should be included in two ways: in Markdown cells and in inline comments in code cells.

Every notebook should start with a header Markdown cell. At the very least, this header should contain a title (which could just be the name of the file), the name of its author (you), the date it was written, and a brief description of what the included code does. You might also want to include a more detailed description of the approach used in the code, if it is complex or may be misunderstood, or references to resources that you used to help you write it. Additional Markdown cells should be included before any cell or group of cells that define a separate "chunk" of the notebook that can be described as a discrete piece of the whole.

All code should also be well-commented with inline comments. This requires striking a balance between commenting everything, which adds a great deal of unneeded noise to the code, and commenting nothing, in which case the reader of the code (or you, when you come back to it later) has no assistance in understanding the more complex or less obvious sections of code. In general, aim to put a comment on any line of code that you might not understand yourself if you came back to it in a month without having thought about it in the interim. Like code organization, appropriate commenting is also something we will be learning about as we write code throughout the semester in CS/DS 125, so while corrections may be made, points will only be taken off for things that have been emphasized in class already.

This style guide from CalTech has some good guidelines for writing comments, starting here.

Code Efficiency

There are often many ways to write a program that meets a particular specification, and several of them are often poor choices. They may be poor choices because they take many more lines of code (and thus your effort and time) than needed, or they may take much more of the computer's time to execute than needed. For example, a certain section of code can be executed ten times by copying and pasting it ten times in a row or by putting it in a simple for loop. The latter is far superior and greatly preferred, not only because it makes it faster to both write the code and read it later, but because it makes it easier for you to change and maintain.

Assignment Specifications

Assignments will usually contain specifications and/or requirements outside of the programming problems themselves. For example, the way you name your files to submit them to the course website will be specified in the assignment. Other instructions may be included as well, so please read the assignments carefully.

Grading Standards

Every criterion will make up an approximate percentage of the grade given to a single programming problem as indicated in the "Approx. % of Grade" column. Points will be assigned for a particular criterion roughly along the lines of the guidelines of the "Excellent," "Adequate," "Poor," and "Not Met" evaluations.

For example, a problem that was "Adequate" in the Program Spec./Correctness criterion, "Poor" in readability, and "Excellent" in all other areas would receive:
0.8*0.4 + 0.6*0.2 + 1*0.2 + 1*0.1 + 1*0.1 = 84%

Criterion	Approx. % of Grade	Excellent (100%)	Adequate (80%)	Poor (60%)	Not Met (0%)
Program Specifications / Correctness	40%*	No errors, program always works correctly and meets the specification(s).	Minor details of the program specification are violated, program functions incorrectly for some inputs.	Significant details of the specification are violated, program often exhibits incorrect behavior.	Program only functions correctly in very limited cases or not at all.
Readability	20%	No errors, code is clean, understandable, and well-organized.	Minor issues with consistent indentation, use of whitespace, variable naming, or general organization.	At least one major issue with indentation, whitespace, variable names, or organization.	Major problems with at least three or four of the readability subcategories.
Documentation	20%	No errors, code is well-commented.	One or two places that could benefit from comments are missing them or the code is overly commented.	File header missing, complicated lines or sections of code uncommented or lacking meaningful comments.	No file header or comments present.
Code Efficiency	10%	No errors, code uses the best approach in every case.	N/A	Code uses poorly-chosen approaches in at least one place.	Many things in the code could have been accomplished in an easier, faster, or otherwise better fashion.
Assignment Specifications	10%	No errors	N/A	Minor details of the assignment specification are violated, such as files named incorrectly or extra instructions slightly misunderstood.	Significant details of the specification are violated, such as extra instructions ignored or entirely misunderstood.

* As a special case, if a program does not meet the specifications at all / is entirely incorrect, no credit will be received for the other criteria either.