Block Comments

Written by admin

Topics: Code, Software Development

Since I seem to be on a “Comment” and “Terseness” rant, I’d like to point out that I dislike block comments for everything but RDoc.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
x ||= ["0"]
=begin
  this is a block comment
  It's good for auto-generated documentation
  , I suppose. 
 
  x.push("1")
 
  But that line of code above might be mistaken 
  for something that executes, if you're not using
  a good IDE with colorization. 
 
=end
puts x.inspect          # ["0"].... NOT ["0","1"]

It’s harder to make that mistake when the code looks like this:

1
2
3
4
5
6
7
8
9
10
x ||= ["0"]
#  this is not a block comment
#
#  x.push("1")
#
#  Now that line of code above shouldn't be mistaken 
#  for something that executes, even if you're not using
#  a good IDE with colorization. 
 
puts x.inspect          # ["0"], just like you'd expect

Given that just about every IDE out there allows you to select a bunch of text and comment it out en-masse, I think the second method works better.

Hopefully, Peter Cooper will forgive me for taking issue with so many of his Ruby Tricks. Most of them are REALLY REALLY GOOD.