Referring to javascript instance methods with a pound/hash sign

Question

This question is similar to Why are methods in Ruby documentation preceded by a hash sign?

I understand why in Ruby instance methods are proceeded with a pound sign, helping to differentiate talking about SomeClass#someMethod from SomeObject.someMethod and allowing rdoc to work. And I understand that the authors of PrototypeJS admire Ruby (with good reason) and so they use the hash mark convention in their documentation.

My question is: is this a standard practice amongst JavaScript developers or is it just Prototype developers who do this?

Asked another way, is it proper for me to refer to instance methods in comments/documentation as SomeClass#someMethod? Or should my documentation refer to ``SomeClass.someMethod`?

Veradia

Answer 1

I think it comes from javadoc.

http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#{@link}

Hedron

Certainly the first place I saw it. It's by analogy to the URL page#fragment syntax for links. – Zosema

Ah. It's specifically stating: package.class#member is any valid program element name that is referenced -- a package, class, interface, constructor, method or field name -- except that the character ahead of the member name should be a hash character (#). – Veradia

"As stated, the hash character (#), rather than a dot (.) separates a member from its class. This enables the Javadoc tool to resolve ambiguities, since the dot also separates classes, nested classes, packages, and subpackages." – Generosity

From the javadoc.html link in this answer you'll find the a lot of information. Relevant information and reasons for hash notation run a word search for: "package.class#member" to put you in the right spot. – Indiscretion

A more direct/complete link to the different syntaxes JavaDoc defines, which you might also see when somebody is using this notation: docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/… – Gangway

Answer 2

No, I have not yet met another JavaScript project that uses this notation.

Something like this is useful in JavaScript, though, because unlike in many languages Class.methodName would refer to classmethods like String.fromCharCode, not instance methods which is what you are more often talking about. The method invoked by myinstance.methodName would be not MyClass.methodName but MyClass.prototype.methodName, and MyClass.prototype is an annoyance to keep typing.

(The standard JS library confuses this by making many instance methods also have a corresponding classmethod. But they're different functions.)

is it proepr for me to refer to instance methods in comments/documentation as SomeClass#someMethod?

Do what you like/find most readable. There's no standard here.

Zosema

Good answer. So if you were reading my documentation and I consistently used # to designate instance methods, you think it would be clear to you? – Veradia

It would be clear to me from other languages. I wouldn't expect JS authors to know it, but hopefully it's grokkable from context! – Zosema

So apparently this project uses it: github.com/mozilla/pdf.js/blob/master/src/display/api.js#L2957 – Anisomerous