[r6rs-discuss] [Formal] #;<datum> comments useless

[Per Bothner]

Trent Buck wrote:
> One that immediately occurs to me is when one replaces a simple
> definition with an optimized definition, and you want to leave the
> original definition as a comment.  A contrived example:
 > ...
>     (define (f x)
>       ;; The original version
>       #;
>       (+ (* x x)
>          (* x x))
>       ;; The optimized version
>       (let ((x* (* x x)))
>         (+ x* x*)))

Not unreasonable, but in this case I think one of these is cleaner:

     (define (f x)
       ;; The following is an optimization of:
       ;; (+ (* x x)
       ;;    (* x x))
       (let ((x* (* x x)))
         (+ x* x*)))

or:
(define (f x)
       #| The following is an optimization of:
       (+ (* x x)
          (* x x))
       |#
       (let ((x* (* x x)))
         (+ x* x*)))

If this is a permanent change, it's worthwhile trying to format
the comment nicely.  Putting a ;; before each line makes it clear
exactly what is commented-out, at the cost that reverting the
commenting-out is harder.

> I hardly think these are "rare".  It's also kind of uncommon for a
> Scheme document to have only one definition at the top level.

Commenting out a top-level definition with a #; is easy to overlook,
making the code harder to read, especially if one uses your suggested
style of putting the #; on the preceding line.

> Very well, here is a real-world example, from some throwaway code to
> turn OpenOffice documents into a plain text format.  Excuse the
> exorbitant length.
> 
>     (define transform
>       (lambda (e)
>         (sxml-match e
>           [(body . ,xs)
>            (fold body "" (map transform (reverse xs)))] ; hack to prevent stack overflow.
>           #;
>           [(body ,(x) ...)
>            (body x ...)]

This is a good example.  But there is still the question if this is the
debugging or production version of the code.  If the latter, you still
want a real comment explaining why the code is commented out.  If the
code is only commented out during development/debugging, there is the
problem that supporting #; may encourage questionable style (to the
extent people agree it is questionable style for production code).
Plus my argument that #; makes it easier to amke mistakes when
commenting out code.
-- 
	--Per Bothner
per at bothner.com   http://per.bothner.com/