inline comments in future release?

[Shadowfirebird]

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

=3Dbegin
I really think that this is ugly and
only good for temporarily commenting
out code
=3Dend

assert_true me.agree( Ruby.shoulddocument, self) ) #most of the time..=

 

[Robert Dober]

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

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

Cheers
Robert

 

[Dave Bass]

assert_true me.agree( Ruby.shoulddocument, 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

 

[Robert Klemme]

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