Bdtyktl

I am thinking about "dissecting" my code with students, going line by line and commenting (why is this the condition of the while? What does this piece of code do?)

A simple example can be found here: https://docs.google.com/document/d/1mxTE_E2_YKq-yhaXAfBxYP11uaRm7bSXTnP55bMnPyQ/edit

However, I would like a better tool for the job. As you can see, in docs, the comments are far away from the code and not linked to their respective by any visual cue. They are also all on the same color.

I tryed some highlighting tools for docs, but they seem to just highlight,not add colored comments

I am looking for ideas, inside or outside google docs, to do the job.

For inspiration (no way am I ever doing something this pretty!) here is an image from a headfirst book

I would suggest two things. Both of them, however, require that you give them printouts of the code so that they can make notations of their own without having to use any tool. Just write on the paper. Also, I'm assuming that your code is in small pieces, say, short methods. For me, a method is long at about five lines and a method that covers a page is incomprehensible. I have anecdotal evidence from industry that the latter is also true.

One method, assuming that you have given students the code is to just project it from your normal IDE and highlight it with the mouse. Ask the students about it and talk about it. Asking is probably more effective. You don't need to write anything.

Another uses a tool like Powerpoint. Build a deck in which each page shows exactly the same code but with different sections highlighted as you desire, using one or more colors. You can flip between pages as you talk, flipping both forward and backward as needed. But, again, ask the students to explain, rather than giving your own explanations. This way you can pick up misconceptions they might have and correct them. Make sure that the code itself has the same alignment on each page. Then when you flip, only the highlighting changes and students don't need to readjust the context.

Perhaps you can project against a writable surface rather than a screen. If you project on a whiteboard (and can ignore the glare) you can use marker pens to annotate - especially when the students say the right thing.

Make it interactive. Broadcast is much less effective.

Also, since you are putting effort in anyway, make sure that you always use intention revealing names in your demo code. Don't use x, y, z, i, j, k. Make the names come from the problem being solved, not the solution. For example counter is a name from the solution. But negative_value_counter is a name from the problem (of counting negative values - duh). In this way, if you are primarily teaching them about how to structure programs, you can focus on the structure (if, while, ...) rather than having them wonder about the purpose of abstract names.

I'm taking a very basic approach when I do it: I use my Editor and comment line by line. This way I can directly show alternatives and effects if something does not work as planned.
Usually I'm developing the code live to avoid that students get distracted by the code to come.
The good thing about this approach is, you can show them how you can develop a program from scratch and how you are digging into the finer aspects of problem solving. E.g. you can "forget" one condition in a loop and create an endless loop - and show them how you can find the mistake.

Another thing I did which comes closer to your UML example: I'm using a surface tablet in my class and sometimes I'm just taking a quick screenshot and use the pen to write on this screenshot. This works nicely and does not need additional tools (once you are having a tablet with pen).

I create code-comprehension sheets outlined in one of two ways (depending on the code): code on the left, with questions on the right, or code with questions interspersed like comments.

There are a few uses for such sheets:

1. Check comprehension of what we've just gone over.


2. Force students to try to examine and digest code prior to going over it together (to increase interest/retention when we go over the material.)


3. Assessments.

Typically I will do this with 1-3 pages of code that has to be understood on several different levels in order to make sense of it. Think objects, or assembly code.