Why are methods in Ruby documentation preceded by a hash sign?

Question

When I see any Ruby method printed in text, it usually appears as:

Class#method

or

#method

Now, I would use:

Class.method

Why are all Ruby methods preceded by a pound sign? Is there any reason for it?

Pepita

When does it date back to? – Barometry

It was first used in the 1st edition of Programming Ruby, published in 2001: ruby-doc.com/docs/ProgrammingRuby/html/preface.html#S10 - the choice of notation was explained more clearly in the 2nd edition released in 2005. – Carmelo

Answer 1

From the rdoc docs (emphasis mine):

Names of classes, source files, and any method names containing an underscore or preceded by a hash character are automatically hyperlinked from comment text to their description.

Phail

Answer 2

Note that the convention is:

Class#method

rather than

object#method

In code you would have object.method, if object was an instance of class. The # convention is not used in code.

From the RDoc documentation:

Use :: for describing class methods, # for describing instance methods, and use . for example code.

Mnemonic

Yes, sorry, Class#Method. Thanks. – Pepita

I know that # is not used in code, but why is it used at all? – Pepita

Answer 3

The # notation is used to refer to the canonical instance method, like String#upcase. The . notation is used to refer to the method of a particular instance, like mystring.upcase. The distinction is made to not imply that a class method 'upcase' exists.

Untinged

Answer 4

I just realized that none of the other answers touch the most trivial aspect of the question: why the # sign?

I have two theories:

1. It might come from Smalltalk, where symbols are written #sym (instead of :sym) as they are in Ruby. So, if you want to refer to a Method object (as opposed to calling a method), then you would call something like Array >> #new. (The >> is itself a method that returns the method passed to it. So, in Ruby that would be Array.method :new.) In Smalltalk documentation, methods are generally referred to as Class>>method, but in Ruby Class:method would have made more sense, except that it is easily confused with Class::method. Therefore, Class#method was chosen.
2. My other theory is that it simply was chosen because # is the comment character in Ruby.

A definitive answer can only be given by whoever invented that convention. If it was invented for the Programming Ruby book, that would be either Dave Thomas or Andy Hunt, but I kind of doubt that. The book came out in 2001, Ruby started in 1993, how were they referring to methods before then?

Frans

I've heard that the pragmatic programmers created the documentation for Ruby as well (they wanted to seed the documentation so that others would be "fooled" into adding to it). git can take you back to 1998, so you could check if Class#method_name happened before the prag progs added it. – Geophagy

I've since heard that documentation did exist before the prag progs started adding it into the source code. – Geophagy

Maybe it's imitating the look of the # anchor syntax in HTML. For example somesite.com/somepage#section. – Professorate

@Professorate I second this. Absent any definitive resources as to why # was chosen, I've always found the most likely explanation to be the anchors used to jump to a particular method in the documentation - Java's use of the same convention is widely believed to be of that origin as well. – Grantinaid

Answer 5

The hash notation was introduced "Programming Ruby - The Pragmatic Programmer's Guide" first published in December 2000.

The "Preface" contains "Notational Conventions":

Within the text, Fred#doIt is a reference to an instance method (doIt) of class Fred, while Fred.new [In some other Ruby documentation, you may see class methods written as Fred::new. This is perfectly valid Ruby syntax; we just happen to feel that Fred.new is less distracting to read.] is a class method, and Fred::EOF is a class constant.

This is clarified in the 2nd edition, published in October 2004:

Within the text, Fred#do_something is a reference to an instance method (in this case do_something) of class Fred, Fred.new is a class method, and Fred::EOF is a class constant. The decision to use a hash character to indicate instance methods was a tough one: it isn’t valid Ruby syntax, but we thought that it was important to differentiate between the instance and class methods of a particular class. When you see us write File.read, you know we’re talking about the class method read. When instead we write File#read, we’re referring to the instance method read.

Ruby itself uses this notation:

> rvm use 1.9.3
Using ruby-1.9.3-p551

> Object.instance_method(:initialize)
=> #<UnboundMethod: Object(BasicObject)#initialize>

It was introduced and formalised by Matz in February 2002:

commit 8210c254bee19294af67bcee0e8f5e02ebb39a60
Author: matz <matz@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>
Date:   Tue Feb 5 07:56:31 2002 +0000

    * io.c (fptr_finalize): should raise error when fclose fails.

    * eval.c (method_inspect): proper output format to distinguish
      methods and singleton methods.


    git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@2046 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

Carmelo

Answer 6

All the answers above you list are correct. The one thing I would add is that the documentation style you said you would perfer

Class.method

would be easily confused with class methods. Since you can call class methods in ruby using the above syntax:

class Foo
  def self.say_hi
    puts "hi"
  end
end

Foo.say_hi    # => prints "hi"

Decapitate

Answer 7

This was mentioned in the JS version of this question, but it seems likely this nomenclature came from JavaDoc where the hash mark is translated directly into an on-page reference, e.g. href="Component.html#getComponentAt(int, int)"

Amortizement

Huh, I'd been wondering why Javadoc requires that usage, but I didn't expect the reason to be so banal. – Upanchor

Answer 8

heff's answer (which I can't comment on due to lack of reputation), that Ruby followed JavaDoc's example, is the best guess in my view. The JavaDoc designers needed or wanted a way to distinguish package qualifiers (which they used the dot for) from class qualifiers (which they used the hash for). JavaDoc's @see and @link tags syntax looks like this:

@see   package.class#member [optional label]
{@link package.class#member [optional label]}

See the documentation of JavaDoc's package.class variant of the @see tag and the documentation of JavaDoc's @link tag, which heff already pointed to.

In JavaDoc, the package name can often be omitted, so that only the Class#member part remains, which looks equally strange as in Ruby, because Java code uses the Class.member syntax, just as Ruby does.

It would be interesting to find out why the JavaDoc designers needed the differing syntax, while the Java compiler does fine with dots for both purposes.

Cocke