Commenting JavaScript functions á la Python Docstrings

Question

It is valid JavaScript to write something like this:

function example(x) {
    "Here is a short doc what I do.";
    // code of the function
}

The string actually does nothing. Is there any reason, why one shouldn't comment his/her functions in JavaScript in this way?

Two points I could think of during wiriting the question:

• The string literal must be initiated, which could be costly in the long run

• The string literal will not be recognized as removable by JS minifiers

Any other points?

Edit: Why I brought up this topic: I found something like this on John Resig's Blog, where the new ECMA 5 standard uses a not assigned string literal to enable "strict mode". Now it was my interest to just evaluate, if there could be uses or dangers in doing such documentation.

Answer 1

There's really no point in doing this in Javascript. In Python, the string is made available as the __doc__ member of the function, class, or module. So these docstrings are available for introspection, etc.

If you create strings like this in Javascript, you get no benefit over using a comment, plus you get some disadvantages, like the string always being present.

Answer 2

You're not writing Python, so don't pretend like you are.

Answer 3

Instead of giving a point to Matt Ball, I am gonna go ahead and put emphasis by repeating it:

JavaScript is not Python.