From: Dave Bass <davebass@...>
Date: 2008-07-27T19:41:38+09:00
Subject: Re: inline comments in future release?

Shadowfirebird wrote:
> assert_true me.agree( Ruby.should(:document, self) )

On a line-by-line basis, it's certainly true that code should be 
self-documenting. But it's no good knowing what each line does if you 
can't see the big picture. Usually you want to see the big picture 
first, before you delve into the details.

Ancient Fortran codes typically started with a nice big block of 
comments describing each subroutine, detailing its calling sequence 
(parameters) and return values, and saying how it worked. I know this 
went out of fashion many years ago, but it's still a good idea IMHO. At 
any rate, I always do it even though my code is solely for my own 
consumption. Time wasting? Not in my experience.

In Ruby the =begin ... =end syntax is the obvious way to do that. My 
only gripe is that no whitespace is allowed before =begin and =end, so I 
can't indent them appropriately. :-(

Dave
-- 
Posted via http://www.ruby-forum.com/.