Answers to Grade Questions

Despite the stated Program Evaluation Criteria, sometimes students turn in work that might charitably be described as `poorly done', and then send e-mail asking about their grades

It's important to understand that over the course of a semester, one or two points on a single homework, or ten points on one exam, won't make the difference of a letter grade. One or two points on every homework will make the difference of a letter grade. Skipping one or two homeworks can make such a difference. Ten or fifteen points on each of three exams will also make such a difference.

In my experience, many students want to do a good job, and will do so if they have a sense of what that is. Most of what I'm going to describe here is stuff that you probably heard from other professors but which didn't sink in. To help it sink in, and to help you develop a sense of what it means to write good code, I've collected excerpts from actual letters I have sent back to students who wanted to know about their grades (all identifying information has been removed). Reading these might help you to better understand what not to do.

1. Your [ quadratic equation program ] rejects A=1, B=2, C=1 (which is zero when X=-1). Your program says "Unable to take the square root of anything <= 0.", but the square root of zero is zero; that's perfectly legal math.
2. Your [ homework ] program contains not a single comment delimiter. Therefore, it is obviously lacking in adequate documentation.
3. (This is for a large, multi-file project in Web Programming.)

   There's nothing called "readme.txt", or "README", or any other such file here. So I sort of have to guess which files do what; the names are okay, but a list would be lots better.

   Looking it over with "more *.php" is my usual way of testing documentation and comments on these projects. So far it's not going well. It starts with "config.php", which is a better-than-average name, but the file itself lacks a lot for headers or other docs. All of the files do.

   There's also a lack of formatting and indentation (which is inconsistent where it exists)[.]

4. Your group's example was especially bad. The only instance of a comment delimiter in [ one of the files ] is a line of code that was commented out. I found no names, no dates, no descriptions, no explanations, nothing.

   It's possible to write good code with few comments, but yours doesn't have ANY. And even if you'd done the basic top-level documentation, this code's readability is a disaster. The code includes the variables "val1" and "val2" -- I wouldn't accept that from Intro students, and I'm certainly not going to accept it [ from graduating seniors ] .

5. [T]he "we could have fixed it" response shows exactly the wrong attitude. Testing and documentation and coding style aren't things you go back and do at the end before turning something in: they are supposed to be an integral part of every stage of program development. Is it your regular practice to write C++ programs with [ lousy variable names ] and then go back to replace all the variable names later? Am I supposed to believe that you make a habit of leaving indentation to the last minute in your other classes?

   The level of documentation, coding style, and testing in this project were just not acceptable. There is no way around it, and there's no nice way to say it: you did a poor job.

   The quality of work was reflected in a poor project grade, and that dragged down your semester average. The response to criticism for a poor job shouldn't be "Oh, my poor GPA, it's not fair!" The proper response is to understand that good coding style and testing actually matter to the quality of your work, and to ensure that you never again neglect standard programming disciplines.

6. (A student who missed a B- by one point was trying to get bumped up one. I noted that if he'd spent as much time polishing his homework he'd have made it easily, by giving him a chart of lost points. I've not included all the homeworks in the interests of space.)

   The one that cost you the most was not following the directions for web page. (By the rules as laid out in the assignment, I could have given you a zero for failing to pass the HTML tester, but I went ahead and counted it anyway.)

       Echo program (uses flags, -b, -n, etc):
           Only "header-style" comments.             -2 points
           Indentation and brace style vary
               randomly and make no sense            -1 point
               (I don't care what style you choose,
                but choose ONE and stick to it.)
   
           Total: 7 points out of 10
   
       RCS:
           Your third revision is 1.3, not 2.1.      -3 points
           The program itself has no comments
               or documentation of any kind.         -1 point
           No indentation of any kind                -1 point
           Code is klunky and repetitive             -0 points (you got a pass)
   
           Total: 6 points out of 10
   
       Web page:
           Does not use frames.                      -4 points
           HTML form does not pass HTML tester       -2 points
           CGI output  "   "    "    "    "          -1 point
           No comments of any kind                   -1 point
   
           Total: 2 points out of 10
   
          

To emphasize the point of this last excerpt: it wasn't that one homework had a low score which made the difference. It was that several of them fell short, some badly. If the other homeworks had been 9s, that 2 on the web page wouldn't have done so much harm. But the others had all been low; it was the repeated pattern of doing sloppy work, over the course of the entire semester, which is what caused the trouble. If it was just one program he did poorly on, he'd have gotten his B-. But it was not just one.

It's not that hard, and it doesn't take very long, to put together a 50-line README file for a project that's 1500 lines in 30 files. The README file would be only 3% of the total, but it makes understanding and grading the project five times easier.

Similarly, it's not that hard, and it doesn't take very long, to think of good variable names, and to put in comments for code which isn't obvious. It's not that hard, and doesn't take very long, to think about the operation of a program and break it down sensibly into functions, and give each function a good name and understandable documentation.

Do good work, and your grade will take care of itself.