The world according to Sven-S. Porst
« Random Links •
Main
• Loo Pod »
405 words
Comments are important. On the web, perhaps, in newspapers and in code of any kind. Writing code, be it TeX, C, HTML, AppleScript, PostScript or whatever, I always feel it's important to state what I am doing and why I am doing it. This will obviously be an advantage for anybody else reading the code and trying to understand what it does. They'll be able to see what I wanted it to do and will equally well be able to point out things I misunderstood. I absolutely hate having to work my way through code where it is hard to see what it does and the author doesn't even state so explicitly, leaving it for me to guess... (and in generic variable names and you'll have a proper rant).
The even greater advantage of comments in my code is of course, that I'll be able to understand myself what I wrote weeks or even months earlier. This is particularly important if you're programming and using poorly documented APIs – Apple's come to mind – where you'll have to do a lot of figuring out what's actually going on because the documentation is somewhere between inaccurate and incomplete. You better note down how you came to do things the way you do and why – so you'll have that information handy in case you need to do it again.
Now the problem is of course that while I like writing comments, it sometimes turns out that I still don't do it enough or my comments just aren't as helpful as they should be. I like to think that code ideally reads like a little story where everything that isn't obvious is made obvious in the comments.
This was an apology for comments and why I think they are important and should be used extensively, so let me make a point here:
It's a fucking disgrace that support for comments in many languages is piss poor.
Most notably, there is no support for nesting comments, meaning that if you comments on a regular basis you will be burnt sooner or later: Say, you have an extensive remark in C, /*...*/, style or in XML, <!-- --> style, in your code and want to comment out a bit of code containing that remark. Welcome to having to remove your old comment (and re-add it if you want to use the code again later on). That's just silly.
July 24, 2004, 0:13
Sounds like you’d be interested in Literate Programming, if you haven’t read about it already. Originally Donald E. Knuth’s idea.
http://www.literateprogramming.com/
July 24, 2004, 21:17
I read Knuth’s account of programming TeX using ‘literate’ techniques a few years ago. It was quite interesting. And while this may have influenced my views on the topic, I like to think that I developed my own, less general (and less elaborated), reasons why this should be done.
While in Knuth’s narrative the advantages of his technique are quite obvious, judging from the source code I saw so far (in open source projects, say), I keep asking myself whether anybody actually uses these techniques. (And what the open source advocates have to say vis-à-vis this situation regarding the ‘superiority’ of the work).
Even at university, while CS students seem to be forced to write proper documentation for their code (and do so grudgingly), iirc the ‘literate’ approach goes a bit further than that.
P.S. Perhaps those sdef files we’re using now are a feeble attempt at such techniques - you generate ‘code’ (scriptSuites) and documentation (scriptTerminologies) out of it…
July 25, 2004, 2:10
