Sunday, March 4, 2012

Ruby: Public/Private Distinction Belongs In Comments, Not Code

Had a minor blog/Twitter skirmish about this a year ago with Loren Segal. Realized why I was right when I revisited TomDoc and took a look at how it handles the public/private distinction.

# Public: Duplicate some text an arbitrary number of times.
#
# text  - The String to be duplicated.
# count - The Integer number of times to duplicate the text.
#
# Examples
#
#   multiplex('Tom', 4)
#   # => 'TomTomTomTom'
#
# Returns the duplicated String.
def multiplex(text, count)
  text * count
end

I'm not out to put words into the mouth of TomDoc's author -- he might disagree -- but I believe TomDoc gets it exactly right, putting that distinction into comments. I firmly believe putting that distinction anywhere except comments is rude and disrespectful to your fellow developers. It goes in the comments because it's opinion.

First, anyone who's done non-trivial stuff with Rails has seen "private" APIs turn effectively public, even if only for brief periods, due to the proliferation of hacks. Second, I think it's presumptuous and inappropriate for developers to set up little obstacles to creative misappropriation. Both these problems stem from one common root: You really can't tell, when you write the code, which parts of it are going to be most useful for other people. Partly because people will do things you hadn't expected, and partly because your code may contain subtle bugs they need to work around.