Documenting code

[traveler]

I have some code to document (more complicated than that below). I'm probably going to use a combination of graphic callouts (lines running from the code to boxes with description) and regular comments. I will be using this code in a classroom and discussing parts of it with the participants. Does the color help? BTW, my brother is colorblind so I understand that it won't help everyone. I will be happy if it helps some.

#use strict
my $foo;

while(<>){
        print func($_);
        $foo++;
}
print $foo;

--traveler

[sschneid]

I personally find syntax highlighting to be incredibly useful. You may want to look into vim, as it does this automatically, and supports exporting your highlighted code to HTML, as well.

-s.

[traveler]

Thanks. In fact, the example was generated by vim!

--traveler

[robartes]

I would personally skip the color. While it certainly helps when writing code (the code color makes it easier to see the code structure at a glance, combined stuff like indentation, of course), I think that when teaching Perl, this will just clutter things up.

It depends on the level of the people you will be teaching, but beginning programmers tend not to differentiate between language statements (such as print) and programmer provided things (such as variables and function names). Putting these elements in different colors will not add to the clarity, I think, but add confusion.

In short, I think that coloring code for teaching purposes might not be ideal, especially if your public is not advanced enough yet to understand why various parts get colored similarily.

Then again, once your public knows why 'print' and 'while' are red, whereas '$variable' and 'function_name' are green, and for sufficiently large code, color does add clarity. Just don't do it too early and don't overdo it.

CU
Robartes- who's married to a teacher :)

[Nkuvu]

I can see your point, but I originally envisioned this as being taught something like "I have set the built in functions to be displayed in red text" from day one.

[Nkuvu]

I agree with sschneid -- in fact, I often have a hard time reading code that isn't colored. I've gotten quite used to comments being colored green, so I either look to green text first or last (depending on the situation).

And even colorblind people can distinguish between shades, so gray text doesn't stand out as much as black text. So by making comments and such lighter, it's easier to ignore when appropriate. You've also added some bold to the code snippet above, and that's not dependent on color.

IMHO, teaching students to read colored code would be about 1000 times easier than teaching them to read mono-color code.

[rjray]

Don't forget to take into account your presentation media. If you are projecting to an overhead, for example. If your example is destined to be on paper at some point, it will almost certainly be printed in gray scales. On the other hand, if it is only going to be on a web site, then you have more leeway.

--rjray

[sschneid]

Good point. I still stand by my original opinion, though; I've printed out syntax-highlighted code and still find the greyscale-highlighting (and bold, etc) easier to read than monochrome text.

-s.

[djantzen]

I'm surprised colors are so popular actually, they always tend to make my eyes hurt, with the exception of commented out sections. In fact, I have to disagree with just about everything said so far :) As a beginning programmer, I think it would have helped me to grok what the different pieces of syntax meant, especially in such a verbose language as Java, my first. Come to think of it, my lab partner used colors in Emacs and did better in the class than I, but then he was also a logician :^P

Nowadays I find that the most important factor in tackling a problem is to get as much of the contextual code on the screen as possible. To that end, on my screen you'll see plain black on white spread across at least two Emacs windows in the smallest possible font that my eyes can bear.

---

"The dead do not recognize context" -- Kai, Lexx

[ajt]

I tend to agree with fever. I'm dyslexic and I find coloured text much harder to read than simple well spaced text. Plus coloured text is expensive to print in colour and when printed in B&W it looses contrast when compared with plain B&W text.

I've tried lots of syntax highlighting tools for code, HTML and XML, and I often find I think it's cool and better than plain unadorned text, until I use it, then I prefer light text (one of only a few colours) on a dark background.

The various societies for dyslexia, blind/partial sighted and reading/learning problems, all have guidelines (often conflicting I might add), but they tend to suggest simple high contrast colours well spaced.

While I accept that you can do what you want on your own when you work on code, when you present it, indeed when you present anything, it's all about clear simple presentation. The same rules that make an article or presentation good apply to anything, code or not.

For example:

• British Dyslexia Association
• RNIB
• Bobby

--
ajt

[Nkuvu]

I'm not sure I understand, fever. You disagree with just about everything said so far, but it would have helped with syntax? Aren't you contradicting yourself there? Maybe it's just that it's starting to get late... :)

[djantzen]

It would have helped me as a beginner, whereas others feel that it's only useful to those with more programming experience. At this point for me colored syntax is just line noise, but the only measure that matters in a discussion like this is what it takes for someone to be productive.

---

"The dead do not recognize context" -- Kai, Lexx

[michaeld]

Actually, I'd only differ between code and comments.
That way, the image will not be too flashy to look at, and at the same time, your students will be able to easily pick out the code/comment as they wish...

Cheers,
Michael.

[PodMaster]

I like syntaxt hilighting, but the problem with it is that its faulty. As such, it will only confuse students, especially since they tend to rely more on the syntaxt hilighter than their brains to detect syntaxt errors. As a teacher, you want to encourage thinking, especially when teaching the basics. I can live with my syntaxt hilighter's quiks cause I know the perl syntaxt basics, and I know the hilighters quirks, and I never stop thinking ;)

MJD says you can't just make shit up and expect the computer to know what you mean, retardo! I run a Win32 PPM repository for perl 5.6x+5.8x. I take requests. ** The Third rule of perl club is a statement of fact: pod is sexy.

[thor]

I like syntax coloring. It helps me to do things at a glance that I would have to otherwise spend more time on. That is a two-edged sword though. You might overlook something because at a casual glance "it couldn't be that".

You might want to check out perltidy's html output if you're going to be doing this for a large number of scripts (plus, then you get the bonus of having perltidy make your code look nice. Not saying it doesn't look nice already...(-:)

thor