[plt-scheme] Commenting code for teaching

From: Eli Barzilay (eli at barzilay.org)
Date: Thu Jan 17 14:48:04 EST 2008

[Sorry, I missed the original post...]

Actually, the annotations part is independent from the handin-server,
and the associated code is not in there.  What I do is roughly this:

* Students submit code through the handin server, which translates the
  file to plain text format in case it's a media binary file (among
  other tasks, like evaluating the submission to make sure it works)

* On my side I collect the files and send them off to the grader/s.

(Note: both of the above can be done with subversion too, the
handin-server has an advantage of being able to evaluate & check the
submission.  It might actually be possible to either combine the
handin server with a subversion backend, or change it to use
subversion for submissions -- which is like turning the handin server
to commit hooks that will do the checking.)

* The server also adds "meta comments" -- which is anything marked by
  a ";>" like this:
    ;;> Student: Foo Bar <foo at bar.com>
    ;;> ... any additional info, like submission time, test failures
    ;;> etc
  (The server will forbid students from using such comments in their

* When the graders receives the files, they grade it and add more such
  meta-comments, with anything they want to say.  For grading, the
  meta comment should have a "<+N>", "<-N>", or "<*N%>" somewhere,
  where `N' is any number.

* When I receive the graded files, I put them back in the submission
  directories which are now available for students to view.

* I then run a grading script that will:
  - verify that except for meta-comments the contents is the same as
    the original submission (in case graders tweak submitted files
    (eg, to make them work so they can be graded))
  - sum up the numbers, multiply by a `<*N%>' factor (which is there,
    for example, for late submissions), and record the total grades
  - also, it converts the graded file to an HTML file that highlights
    meta-comments, so students have a very visible way of seeing the

Getting all of this to work is not too hard, and the result is much
easier time for me, for the graders, for students, and for the little
forest that was not cut down.  Except for tests, I haven't had a paper
submission of homework for several years now.

On Jan 17, Matthias Felleisen wrote:
> Eli and Matthew and a bunch of others have evolved the hand-in
> server to the point where my graders add some annotations to the
> grading file, say,
>   <score: +1>
>   <template>Use your index card, Luke</template>
>   etc
> and then they return it electronically to students. Style files and
> some other background magic turn the comments and scoring edits
> "red" and the code shows up in blue or black.
> I like Matt's suggestion for svn. I have used it in upper-level
> courses. I'd really love to see a combination of the two.

          ((lambda (x) (x x)) (lambda (x) (x x)))          Eli Barzilay:
                  http://www.barzilay.org/                 Maze is Life!

Posted on the users mailing list.