19

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.

Boldewyn
  • 81,211
  • 44
  • 156
  • 212

2 Answers2

15

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.

Ned Batchelder
  • 364,293
  • 75
  • 561
  • 662
  • 1
    Some JavaScript engines optimize this and remove the string. `(function(){"foobar"}).toString(-1) === "function () {}"` in Spidermonkey. – Eli Grey Nov 10 '09 at 00:33
  • That's cool, but there's still nothing to be gained by doing this in Javascript. Why subvert the design of the language? – Ned Batchelder Nov 10 '09 at 01:48
  • I'm not fully sure, if it is subversion: http://ejohn.org/blog/ecmascript-5-strict-mode-json-and-more/ – Boldewyn Nov 10 '09 at 07:36
  • You can modify the technique so that you do get the benefits of introspection and being able to see the strings in an interactive javascript shell: `foo = function(bar) { return bar * bar }; foo.__doc__ = 'foo(bar): returns bar squared';` Then in a shell, you get something like this: `> foo { [Function] __doc__: 'foo(bar): returns bar squared' }` – Vineet Mar 21 '12 at 01:53
1

I was looking for a way to add multi-line strings to my code without littering it with \n's. It looks like this module fits the bill: https://github.com/monolithed/doc

Unfortunately, the comments won't survive minification, but I suppose you could write a compile task to convert docstrings to "\n" format.

adampasz
  • 1,065
  • 9
  • 10
  • That's very interesting, but, please be patient with me, I don't see the relevance to the question. Welcome to StackOverflow, by the way! – Boldewyn Jul 05 '14 at 19:10
  • 1
    It is a JS equivalent to a Python docstring. So you add your doc as a comment, and then can access it via the __doc__ property. You can see some examples in the tests here: https://github.com/monolithed/__doc__/blob/master/tests/__doc__.js I'm not entirely clear what you're trying to do, but you could use this approach for documentation. – adampasz Jul 06 '14 at 23:18
  • Ah, I see: I have the advantages of Python's `__doc__` in standard JS comments, so no need for the experiments with strings... Good idea. (My original intention with the question was to evaluate the very possibility of using strings w/o assigning them, but I agree, it's pointless without use case.) – Boldewyn Jul 07 '14 at 07:40
  • By the way, I'm not a huge fan of how `__doc__.js` modifies the object prototype. But you can easily just extract a comment from a function with regex, like I did in the extractFirstComment function here: https://github.com/adampasz/docopt-js-shim/blob/master/index.js – adampasz Jul 08 '14 at 18:34
  • For anyone reading this today, [template literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) were introduced in ES2015 and facilitate multi-line strings without the explicit use of `\n` characters. – Magnus Lind Oxlund May 27 '19 at 10:03