[plt-scheme] Commenting code for teaching

On Jan 17, 2008 1:06 PM, Ivanyi Peter <pivanyi at freemail.hu> wrote:
>  on their written code. I am looking for a tool or a way to do this. I could use normal comments,
>  but I imagine something more sophisticated, something like a transparent layer on top of
>  the code.
>  Does anybody know a tool like this?
>  Any idea?

Hi Peter,

I once experimented with converting code to PDF, and then using some
kind of PDF editing tool to mark up the code that way. I even
experimented with hand-written comments using a tablet. Ultimately, I
found the tools to be awkward at best.

This last semester, I had required all of my students to use
Subversion for their work as a part of the course. This actually had
many benefits that I hadn't anticipated; ease of grading/comments was
one of them. My process typically looked like:

1. Do an 'svn up' in every repository. This was accomplished by a
one-liner on the bash prompt.
2. In each directory, open all the files from a given assignment.
3. Because the students were required to write tests for every
function they wrote (an extension of the "Examples" part of HtDP), I
generally just executed each file.
4. I read their tests, and where I felt the tests were light, I read the code.
5. I used standard block comments with a standard header (highly
visible) to add notes to their programs.
6. I did an 'svn st' to get a list of files I changed.
7. Wrote each student with a list of the files that changed.

Upon hindsight, I could have scripted steps 6 and 7, since their
repositories were named for the first half of email addresses.

Anything I didn't like, students were welcome to revise. As a result,
I graded homeworks harshly, and they had to engage in a revision
process to improve their tests and code. As this was the first time I
had run a course this way, I think there are a number of things that
need revision---but that will come with time.

I don't know if that helps you much. But that's how I've handled this
question, at least most recently.

Cheers,
Matt