6 ms·

So, is this is a point in favor of not commenting your Javascript code or using inline docs? Historically, I preferred to use inline JsDoc style comments as th

So, is this is a point in favor of not commenting your Javascript code or using inline docs? Historically, I preferred to use inline JsDoc style comments as the source of documentation for my public APIs. Recently though, I decided that I didn't like them and that I wanted something better. I was hoping to find some tool that parses my JS to AST, figures out what was being exported (e.g. what was public) and writes a JSON document that I could diff over time, to figure out what was documented and what wasn't (in my external docs). So far, I have found this project called `doctor` which sounded close to what I'm looking for, but it still relies on comments ~ https://github.com/jdeal/doctor https://github.com/jdeal/doctor ~ So, I might have to write it myself using something like Esprima to get the AST...

madflame991 11y ago
> So, is this is a point in favor of not commenting your Javascript code or using inline docs? You can of course strip comments when making builds. In fact you can even write functions of more than 600 chars and get away with it as long as you use a minifier. If you have a minified function of more than 600 chars then that's a bulky function which should instead be split in smaller ones.
xlm1717 11y ago
I wonder what performance gains/losses you would experience if you had the comment outside the function block, before the function declaration.
- STRML 11y ago
  Exactly, if the comment were outside the function, there would be no issue.
  - WorldWideWayne 11y ago
    If the function is nested within another function, then the comments to document the inner function are going to exist inside the outer function. And having nested functions is a very common scenario in JS.
ep103 11y ago
no, just minimize your code prior to production, and that'll rip out the comments. That's been best practice for years.
- lostPixels 11y ago
  No one minifies NodeJS code. The reduced file-size of minified JS is irrelevant on the server.
- nacs 11y ago
  > just minimize your code prior to production In frontend JS code sure, but minifying backend node.js code is certainly not "best practice".
  - draperp 11y ago
    Exactly. And if you did, you would have to look at source maps to decode your stack traces.
untog 11y ago
As others have said, you can always strip comments in production builds. But I agree that this is utterly silly - I'd like to see a movement to deprecate including comments in parsing at all. Anything that makes use of such a feature is hacky weirdness from the start.
- STRML 11y ago
  Function.prototype.toString() should be deprecated anyway. There are very few to no legitimate uses of it that are any better than awful eval() hacks. Re: this comment, if you just don't make huge comments inside the body, but rather above it - as is the usual standard - this is less of an issue.
  - draperp 11y ago
    Every JS dependency injection framework that I've ever seen uses it.
    - STRML 11y ago
      Yes, and that's widely been regarded as a mistake. Now that we have ES6 imports and wide CommonJS support I don't see any good reason to use hacky DI with Function#toString.
    - untog 11y ago
      Serious question: why use a dependency injection framework with JS?
  - BinaryIdiot 11y ago
    > Function.prototype.toString() should be deprecated anyway. There are very few to no legitimate uses of it that are any better than awful eval() hacks. The toString() on a function is very useful in more ways than awful eval hacks. The most useful way is how I use it in msngr.js for creating keys for methods that handle events. So let's say your custom object has a way to handle events. Surely you want to allow more than one method to be hit for each event, right? So internally to your object you keep track of this by the method's contents as a sort of key or hash that always points to that specific method. Then you can remove handlers by simply passing in a method. No requiring special keys or anything to identify a function as a function is its own key. Make sense? It's most useful for developers who work on frameworks or objects that require some custom eventing that can be used by multiple places. If you really want to deprecate this functionality then you need to provide a way to hash to create a unique key based on a function itself. The only other way around it is adding more verboseness to the language or event handler calls which doesn't add anymore clarity.

madflame991 11y ago

> So, is this is a point in favor of not commenting your Javascript code or using inline docs? You can of course strip comments when making builds. In fact you can even write functions of more than 600 chars and get away with it as long as you use a minifier. If you have a minified function of more than 600 chars then that's a bulky function which should instead be split in smaller ones.

xlm1717 11y ago

I wonder what performance gains/losses you would experience if you had the comment outside the function block, before the function declaration.

STRML 11y ago
Exactly, if the comment were outside the function, there would be no issue.
- WorldWideWayne 11y ago
  If the function is nested within another function, then the comments to document the inner function are going to exist inside the outer function. And having nested functions is a very common scenario in JS.

ep103 11y ago

no, just minimize your code prior to production, and that'll rip out the comments. That's been best practice for years.

lostPixels 11y ago
No one minifies NodeJS code. The reduced file-size of minified JS is irrelevant on the server.
nacs 11y ago
> just minimize your code prior to production In frontend JS code sure, but minifying backend node.js code is certainly not "best practice".
- draperp 11y ago
  Exactly. And if you did, you would have to look at source maps to decode your stack traces.

untog 11y ago

As others have said, you can always strip comments in production builds. But I agree that this is utterly silly - I'd like to see a movement to deprecate including comments in parsing at all. Anything that makes use of such a feature is hacky weirdness from the start.

STRML 11y ago
Function.prototype.toString() should be deprecated anyway. There are very few to no legitimate uses of it that are any better than awful eval() hacks. Re: this comment, if you just don't make huge comments inside the body, but rather above it - as is the usual standard - this is less of an issue.
- draperp 11y ago
  Every JS dependency injection framework that I've ever seen uses it.
  - STRML 11y ago
    Yes, and that's widely been regarded as a mistake. Now that we have ES6 imports and wide CommonJS support I don't see any good reason to use hacky DI with Function#toString.
  - untog 11y ago
    Serious question: why use a dependency injection framework with JS?
- BinaryIdiot 11y ago
  > Function.prototype.toString() should be deprecated anyway. There are very few to no legitimate uses of it that are any better than awful eval() hacks. The toString() on a function is very useful in more ways than awful eval hacks. The most useful way is how I use it in msngr.js for creating keys for methods that handle events. So let's say your custom object has a way to handle events. Surely you want to allow more than one method to be hit for each event, right? So internally to your object you keep track of this by the method's contents as a sort of key or hash that always points to that specific method. Then you can remove handlers by simply passing in a method. No requiring special keys or anything to identify a function as a function is its own key. Make sense? It's most useful for developers who work on frameworks or objects that require some custom eventing that can be used by multiple places. If you really want to deprecate this functionality then you need to provide a way to hash to create a unique key based on a function itself. The only other way around it is adding more verboseness to the language or event handler calls which doesn't add anymore clarity.