November 21, 2003
The mixed bag of syntax highlighting
Like so many other programmers, I use a syntax-highlighting editor. (Well, OK, I'm an emacs user, so technically I'm using a syntax highlighting operating system, but we'll let that one slide) I have noticed one interesting thing about using it, though--I comment my code less.
I noticed this the other day when I printed out the code for the compiler module I'm working on. In the editor, with colored highlighting enabled, it makes sense what's going on, and everything's reasonably obvious. On paper, though, in black and white with no highlighting the lack of comments was much more obvious, and the code itself didn't make a whole lot of sense. It's not even the amount of code that's visible, as I've got a near-obscenely sized set of monitors on my desk.
No, I don't know if this means anything. And yes, I know about a2ps, and I do use it, though it's highlighting's not as good. (Though I'm not sure now whether I want a good PIR higlighting mode or not, now)
It might be an indication that your code isn't quite as well documented as you think it is. Mine certainly isn't, though I'm going to go fix that.
Posted by Dan at November 21, 2003 03:03 PM
| TrackBack (2)
Another possibility is that you're now relying on the cues provided by the highlighting to make any sense out of code. I, being used to Xcode's syntax highlighting, find it difficult to read _any_ large sequence of code in black and white, good comments or not.
Not that I want to discourage you or anyone from commenting code, of course. :)
As a side-note, (perhaps you know this already?) Emacs can generate 'syntax-highlighted HTML' through the htmlize-buffer function. Perhaps that would aid the printouts? It's no solution to the underlying problem though.
So, uh, why were you printing it out?
I find colored syntax highlighting highly confusing. At least with Perl code I find it much easier to read and follow when it's mono-colored and just indented well (and maybe cued well by using appropriate idioms in all places).
Since you are already using emacs, it might be worth checking out its ps-print-buffer function; especially ps-print-buffer-with-faces variant. Also, there is ps-print-region-with-faces for those times you want to print only a part of the file. I find it better than a2ps. However, I mostly use enscript to do my printing of perl code (when I need it).
I have to add that I use Xemacs, but I expect emacs to have the same (or similar) features.
Hrm. I never looked to see if emacs would print with faces (I am using xemacs for the most part, but all the variants are emacs to me) but I should've expected that it would. Now if I could figure out how to get 2-up printing out of it, that'd be perfect. (I'm sure it does, while generating a markov-chain-driven Zippy quote variant of the buffer, but that's neither here nor there :)
Being a vim/gvim user myself, I fully understand your problem. However I find myself cursing big comments in printouts, because I cannot quickly scan past them to see if I realy need to read the comment, or if the code explains itself.
But your correct, I have a tendency to write code first (since syntax highlighting keeps track of it) and then go back and comment. I used to do it the other way around, before I became a vim user.
I use GNU Emacs, but try reading the commentary at the top of ps-print.el (search for "N-up Printing").
> Being a vim/gvim user myself, I fully understand your problem. However I find myself cursing
> big comments in printouts, because I cannot quickly scan past them to see if I realy need to
> read the comment, or if the code explains itself.
You might want to try out vim's folding feature. There is some good documentation on it in chapter 28 of the vim user's manual: http://vim.sourceforge.net/htmldoc/usr_28.html
Using the folding feature you could, for example, summarize a long comment on its first line and fold the rest. Your long comment is converted to a single line which can be opened by moving your cursor over it.
There can also be nested folding and automatic folding. All very, very handy for browsing through large, complicated sections of code.