DEV Community

loading...

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

Collapse
stereoplegic profile image
Mike Bybee • Edited

Using JSDoc to define types, instead of that superset thingy that everybody loves, is so bae. 😍

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

configure

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)

usage

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": [
            "/**",
            "@func",
            "$1",
            "",
            "@param {$2} $3",
            "@return {$4}",
            "*/",
        ],
        "description": "comment block template for funcs"
    },
Collapse
stereoplegic profile image
Mike Bybee • Edited

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

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.

Forem Open with the Forem app