RE: PPIG discuss: Comments continued...

[Stuart Watt (cmssnkw)]

Title: Message

An interesting point.  I looked through some of my old code (> 4 years old, and in Lisp which I don't use much now) and it seemed like the one thing I almost never do is comment code.  Many of my comments were contextualisers.  In effect, I used comments to indicate what else might constrain or influence the bit of code that followed.  Others would mention design decisions and draw them in just before a bit of code. 

 

Whether these comments were/are useful to anyone else, I have no idea (but probably not!).  Certainly I suspect I used them as part of the coding process -- as a way of elaborating design decisions to a point where I could code them.  By and large, I wrote comments before code rather than within it or after it, and I think I was trying to use comments to alert various cause-effect chasms, although I've only just realised this now.  In fact, I think I was using comments to draw attention to things which weren't in the code itself, rather than to explain things which were.  For example, quite a few comments elaborated contexts where procedures couldn't be used, or where certain things needed to be set up first.  Some, but actually not many, of these could be made explicit in code by assertions of one kind or another.

 

It may be that this is an effect of the kind of system I was building (it was Hank, written in Lisp) and the fact that 80-90% was interface.  These are perhaps less algorithmic in nature, and all sorts of odd control-flows can happen as a result of errors, and so on. 

 

I'm now mostly a Perl user, and I still use comments separately from Perl embedded documentation, and I suspect API documentation is very different to the way I was using comments at least. 

 

... an helpful discussion, thanks ...

 

All the best

Stuart

=================================
Dr Stuart Watt
School of Computing, The Robert Gordon University,
St. Andrew Street, Aberdeen, Scotland, AB25 1HG
Email: [EMAIL PROTECTED] / [EMAIL PROTECTED]
Tel: +44 1224 262713; Fax: +44 1224 262727
URL: http://www.scms.rgu.ac.uk/staff/sw/

-----Original Message-----
From: Chris Douce [mailto:[EMAIL PROTECTED]]
Sent: 07 October 2002 13:31
To: '[EMAIL PROTECTED]'
Subject: PPIG discuss: Comments continued...

Hi,

While coding a few moments ago, I realised that I was using comments for something else other than merely explaining code.  I composed the following line:

        HRESULT error = e.GetErrorCode();       // 23 = data error

When I finish trying to figure out how come my error is occuring, I plan to expunge this nasty and unclear comment from the source forever.

I use these comments to reduce my load on short (or perhaps medium-term) term memory.  M$ IDEs allow you to define a categories of 'comments'.  Common ones that I have begun to use are '//TODO:' and (shhh!, don't tell anybody) '//HACK:'  You can even define you own, like //BODGE:, //FUDGE: or //FLAKEY:  When you compile, the compiler can potentially be used to alert you about your bodges and fudges.

I have no idea how long my temporary 'working memory' reminder comments last.  It depends upon what I'm called away on.  They can be increibly very idiomatic.  Relating to one Ron proposed, I could feel myself writing something like /* p.23, green file, back of drawer */.

It may be interesting to find out how long these comments last.  Perhaps by analysing a corpora of software versions (in-between 'true' releases) it may be possible to get a view about transitory comment lifetime, if this is considered an worthwhile endeavour.

I find that I rely on external notations constantly while developing software, scraps of paper, UML (occasionally), and comments.  Comments is one of the tools that I use (probably without realising) on a daily basis.

Cheers

Chris