On Thursday 05 July 2001 23:53, Yukihiro Matsumoto wrote:

> For (a), we already have =begin/=end; for (b), I think we can use
> =begin/=end too.  RDtool does not handle embedded documentation with
> tag other than "RD", so that you can do

Which IMO is more than sufficient. If you want to have an end-user manual, 
then write one! For documenting code as part of a project, the RD way works 
fine for me :-) 

> =begin debug
>   ... code to escape out ...
> =end
>
> without showing code in the RD processed documentation.

Cool! I didn't know that! As you say, that problem is solved :-)


> So, I think, we have to discuss about (c) inline comments only.
> What do you think?

Well, perhaps the "easy" solution here is to refer to Linus Torvalds' opinion 
of inline comments: evil!

Personally, I have come to share this feeling after reading lines of code 
with lots of // inline comments from one of our developers. It's hard to read!
It is bad enough when these are ENDline comments. I would think comments 
burried within lines would be worse. I can't really say as I have no 
experienced it; I can't really say that I want to experience it! :-)

While there may be some (minor) justification for ENDline comments in c++. 
IMO there is little or none for an expressive language such as Ruby. Blcok 
comments explaining the thinking behind the code and/or offering the intent 
of various parameters passed to a method should IMO be more than sufficient. 
Yes, it is a little harder to organize and write these things as blocks, but 
it is also easier to read and understand, which, after all, is the purpose of 
commenting, isn't it?

Regards,

Kent Starr
elderburn / mindspring.com