Inline comments in future release?

Ruby
21

Heh, timely:

“You should always write your code as if comments didn’t exist.”
– Jeff Atwood, July 24
(http://www.codinghorror.com/blog/archives/001150.html)

–
Avdi

Home: http://avdi.org
Developer Blog: Avdi Grimm, Code Cleric
Twitter: http://twitter.com/avdi
Journal: http://avdi.livejournal.com

22

On Thu, Jul 24, 2008 at 11:57 PM, Mike S. [email protected]
wrote:

ha ha sorry if I was unclear. I meant comments that can have more code
after them on the same line.

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

There is no general case, but you can do terrible things if you must,
e.g.

x += “x means total but I was too lazy to name it such” && 42

There is no way to bare such crime :wink:

Cheers
Robert

–
http://ruby-smalltalk.blogspot.com/

There’s no one thing that’s true. It’s all true.

23

My 10p:

/* this does look too much like a regex for my comfort */

but this is a pain

in the neck, leading me

to make terse, short

comments, even when

I really need to make

a longer one

=begin
I really think that this is ugly and
only good for temporarily commenting
out code
=end

assert_true me.agree( Ruby.should(:document, self) ) #most of the
time…

On Fri, Jul 25, 2008 at 6:10 AM, Peña, Botp [email protected] wrote:

vs

–
Me, I imagine places that I have never seen / The colored lights in
fountains, blue and green / And I imagine places that I will never go
/ Behind these clouds that hang here dark and low
But it’s there when I’m holding you / There when I’m sleeping too /
There when there’s nothing left of me / Hanging out behind the
burned-out factories / Out of reach but leading me / Into the
beautiful sea

24

On 25.07.2008 00:30, Mike S. wrote:

fair point, it can make things hard to read if you’re not careful

my main concern is that so much code goes uncommented, and the rdoc
comments being outside the body of the method contributes to an attitude
that allows this.

so many of the quality ruby libraries are so flexible and so meta that
it would be great to have more blow-by-blow explanations sometimes!

That’s more a question of programmer discipline than of having inline
comments available. I doubt there is much good code around that
actually comments /in line/. If you have an expression that large that
you need to individually comment on parts then you probably either
choose bad variable names or crafted a too complex expression in the
first place.

Note also that you can break up expressions in a way that you can use
line comments to comment parts if you wish so:

robert@fussel ~
$ ruby <<XXX

x = 1 + # basic offset
10 + # another unimportant number
123 # the final value
puts x
XXX
134

robert@fussel ~
$

A similar thing can be done with regular expressions using /x switch.

Kind regards

robert

25

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. :frowning:

Dave