Documentation/docblocks

[stephan-v]

I am wondering why there is no section of documentation or docblocks. Is it conventional to leave them out? What is the reason I don't see any docblocks in the open-sourced projects you guys have?

I would love to hear thoughts about using docblocks in Javascript. I find them really helpful when I am programming PHP. Especially if your IDE has support for it and can help you out with the documentation.

[ljharb]

Comments in code should not describe "what" - rather, they should primarily describe history/motivation.

If by "docblocks" you mean "JavaDoc"-style documentation, including parameters and return values, then that's exactly the wrong kind of comments. If your code isn't self-documenting, then it's not clear enough.

You're right that the https://github.com/airbnb/javascript#comments section doesn't contain anything about this, but it should.

[stephan-v]

If your code isn't self-documenting, then it's not clear enough.

Although I agree with this, IDE's can also help you a lot if you supply them with proper context in a JSDoc format. It is not about describing the code to you or other developers. It is about describing the code to your IDE.

[ljharb]

Modifying your code to help your tools in a way that doesn't help humans indicates inferior tools.

There shouldn't be a need to use an IDE as a crutch in any language, but definitely not in JS - what specific features are you referring to that the IDE can't figure out without jsdoc comments?

[sean-ww]

With good DocBlocks in php you don't have to read the code. I think that's the point. You can understand large frameworks by skimming through the DocBlocks without reading any code. Why should we have to read your code unless we're directly editing it? Surely we just plug into it. If it's a class, method, whatever... a DocBlock helps us do that.
To me most php is way more readable than the majority of JavaScript that gets churned out.

[ljharb]

The goal should be to only read the code to understand it.

[ItamarShDev]

Just here to raise another point in favor of JSDocs.
When writing in a team , the JSDocs add the autocompletion and intellisense in IDE and code editors (such as VScode), which helps the developers to use the right method and be sure they pass the right arguments to it.

I agree the code should stand for itself and should not be covered and explained with comments and docs.
But I also think JSdocs can help the developer by preventing him from reading any single utils method his/her teammate wrote in the past.