4
$\begingroup$

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

Head first diagram

Improve this question
$\endgroup$
1
  • $\begingroup$ How do you intend to use the output from the "tool"? Is the objective to use it in a visual interactive presentation (such as projected during a lecture), or in a static context to which the students have current and future access (such as shared docs in Google Docs), or even a printout handed to the students prior to or during the presentation? $\endgroup$
    – Gypsy Spellweaver
    Dec 23, 2018 at 0:43

4 Answers 4

Reset to default
5
$\begingroup$

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.

Improve this answer
$\endgroup$
4
$\begingroup$

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).

Improve this answer
$\endgroup$
5
  • $\begingroup$ I disagree about line by line comments. It is, in particular, a terrible coding practice. If the code doesn't speak for itself it is broken. If the comments and code don't agree, they are probably both wrong. If you do this as an active practice when demonstrating, I fear that the students will want to take it up themselves. In professional circles using high level languages (not assembler) inline comments are considered to be a code smell. Don't encourage it. The solution is (a) better names and (b) shorter functions/methods. Then all you need to comment is the intent using, say, javadoc. $\endgroup$
    – Buffy
    Dec 22, 2018 at 19:55
  • $\begingroup$ @Buffy I agree if the students are a bit more advanced. But for beginners it is helpful to explain basic concepts again. E.g. "why is this a pointer" or "why do I have to check for a certain condition". Of course, speaking names are a must! $\endgroup$
    – OBu
    Dec 22, 2018 at 19:59
  • $\begingroup$ You can do that without inline comments. Don't teach them to do things that you don't want them to do themselves. A hand written comment on an overlay isn't the same thing as an inline comment. "But teacher does it. Why shouldn't I?" $\endgroup$
    – Buffy
    Dec 22, 2018 at 20:03
  • $\begingroup$ Or use pair learning and have one student explain verbally the code of another as it is being written. $\endgroup$
    – Buffy
    Dec 22, 2018 at 20:05
  • $\begingroup$ Always try to organize your teaching so that you never have to unteach anything. Don't lead them to bad habits of work or thought that you will have to tell them later not to do that. You can be incomplete in explanations, metaphors, etc, but don't take them down the wrong path thinking that you will show them the better path later. It is a bit harder to always consider that, but necessary IMO $\endgroup$
    – Buffy
    Dec 22, 2018 at 20:13
4
$\begingroup$

You need to know about http://pythontutor.com/ - they have line-by-line execution and a diagram showing memory and how it changes. They also have more than just Python, they have Java, C, C++, JavaScript, & Ruby

I have used this resource in my classes and it makes it so amazing to explain how memory, references, and classes work. The C tutor really helps with pointers as well.

Improve this answer
$\endgroup$
1
  • 1
    $\begingroup$ Welcome to Computer Science Educators! Nice first contribution, and I hope we see more of you around :). Once you have the rep, feel free to visit the chat room and introduce yourself. (It's been slower going in the chatroom lately, but there's almost always one of the site regulars around, and you can type @ and any recently posting user (such as @buffy, @gypsyspellweaver, or @beni) to ping them and get a greeting :) $\endgroup$
    – Ben I. ♦
    Dec 28, 2018 at 19:06
3
$\begingroup$

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.

Improve this answer
$\endgroup$

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.