[WorldWideWayne]

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 ~ So, I might have to write it myself using something like Esprima to get the AST...

[untog]

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]

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.

[BinaryIdiot]

> 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.

[draperp]

Every JS dependency injection framework that I've ever seen uses it.

[untog]

Serious question: why use a dependency injection framework with JS?

[STRML]

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.

[WorldWideWayne]

Thank you. So, due to the extra work that is required I'm going to say YES - this is one point in favor of not preferring inline docs.

I think all the dissenters missed that part (about it being "one point" in favor/not in favor). I thought programmers were supposed to be good with subtle details, but it seems like the majority of them lose that ability when talking about religious topics.

[xlm1717]

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

[STRML]

Exactly, if the comment were outside the function, there would be no issue.

[WorldWideWayne]

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.

[madflame991]

> 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.

[ep103]

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

[nacs]

> just minimize your code prior to production

In frontend JS code sure, but minifying backend node.js code is certainly not "best practice".

[draperp]

Exactly. And if you did, you would have to look at source maps to decode your stack traces.

[lostPixels]

No one minifies NodeJS code. The reduced file-size of minified JS is irrelevant on the server.