DEV Community

Discussion on: Friday Fun Post: fetch lyrics from a public API

functional_js profile image
Functional Javascript Author

I concur.

You know another nice benefit of JSDoc is that it forces one into the habit of documenting one's code. Every func tells a story.

All my func are documented. (Well some older one's not yet, but I'll get to them the next time I have to deal with them :)

Here's my comment snippet.


in vsc -> cmd-shift-p -> Preferences: Configure User Snippets -> snippet.code-snippets
then add the json code block below
(the filename might vary. javascript.code-snippets is another common name)


Put your cursor on the line above the function -> type com -> hit cmd-spacebar -> in the popup-dialog hit enter on the com entry.

"commentSnippet": {
        "scope": "javascript,typescript",
        "prefix": "com",
        "body": [
            "@param {$2} $3",
            "@return {$4}",
        "description": "comment block template for funcs"
stereoplegic profile image
Mike Bybee • Edited on

It's so funny to me when I hear "comments are a code smell" (how dare you not assume your code is so amazing anybody can pick it up in its entirety at first glance without documentation) but pilling on extra, nonstandard syntax - both inline and in separate definitions - somehow isn't to many of the same people claiming comments "smell."

Thread Thread
functional_js profile image
Functional Javascript Author • Edited on

Yes, one of the fallacies in the industry is the concept of "self-describing code".

As if just by choosing the right names for the identifiers, the code will clarify all ambiguity.

No such code will tell you "why" the code exists. And that is what most needs to be explained.