Remove require-jsdoc

[desandro]

End-of-Life for Built-in JSDoc Support in ESLint

The require-jsdoc and valid-jsdoc rules will be deprecated. These two rules will remain in ESLint but we will no longer add new features or fix bugs for them. These rules may be removed in a future major release of ESLint.

I recommend removing require-jsdoc all together. I find it more a nuisance than useful. If we do want JS Doc stuff, then we can add it back with eslint-plugin-jsdoc

[jakefentress]

Totally understand - this rule annoys me more than any other. But, it annoys me to get me to do some documentation I should have done to begin with. Short of going to typescript, I find it helpful to document parameters and the types of data they are expecting.

Do you have any thoughts on how we might approach documentation and/or encourage the team towards documentation without this?

[BrianaCamp]

TEAM KEEEEEP

[lea37]

Team keep IF we can customise the rules. Please show me how to turn off some stuff like return 😅

[nerdpruitt]

I like having something that pesters me to add documentation, but I would like to relax the rules. For example, sometimes param or return descriptions can be redundant and not all that useful, and you can turn those off with requireParamDescription and requireReturnDescription

[printerscanner]

I personally don't like the required parameters part of this.

1. I have trouble remembering the syntax, and
2. I don't find it to be the most straightforward way to describe a function's purpose. And then a comment can end up having enough technical jargon in it that it's easier to just read the code (because at least it's colorful in the code).

But, I agree with Sandy that if it's a contentious issue, that means we should keep it.

[jakefentress]

per @nerdpruitt:

I like having something that pesters me to add documentation

I agree. Interestingly, having strict rules here doesn't mean that you add accurate or meaningful documentation. Sometimes a simple "psst, don't forget to document this for future you and your teammates" is probably the best thing we're trying to achieve here.

For me, knowing the type of data expected is helpful. I guess that's why typescript has really taken off, but I don't want that level of forced conformity, so forcing it here feels maybe like the wrong thing.

I don't want to use Ashur's words in a way he might not have intended, but I do think having a team culture of documenting is a good thing. I've been too lax there in the past — just trying to move fast, thinking how I write things is plenty self-documenting, deadlines, etc — and we can see how that has made it harder for people to get up to speed.

[ashur]

tl;dr — I think tooling that enforces some kind of documentation is important as part of our collective code building; whether that's require-jsdoc, or something else that helps us maintain what I see as benefits of documentation, I'm game.

Note — This is primarily in reference to non-TypeScript projects ☺️

Benefits of Documentation

Things I really appreciate from documented code:

• Showing my work — it's an inline artifact of what I was thinking at the time I wrote that code, and how I intended it to be used
• Increased speed of understanding — it's slower the first time to document, sure, but the next time I come back I can just read the CliffsNotes instead of the whole book
• Increased speed of usage — I get TypeScript-like autocomplete of those functions and their parameters in my editor, which speeds me up during development

JSDoc is a little goofy and maybe kind of old, but it has a nice, cross-language history and lots of native support in tooling.

In Practice

JSDoc supports a ton of properties, but my ideal block looks something like this:

/**
 * Shortest possible summary of what the function does
 * @param {type} name - optional summary where warranted; use your best judgment
 * @return {type}
 */

Summary

/**
 * Shortest possible summary of what the function does

Helps me understand what the function does without having to read and interpret the code. Sometimes I'm just perusing things rather than using them (reading utility functions, filters, shortcodes, etc.) just to familiarize myself with a codebase.

This can feel redundant for very simple functions. I definitely get that! My personal opinion is to trust your best judgment — can the next developer who looks at your code:

• PR reviewers
• new folks who are onboarding
• you in six months 😅

understand what it does just by reading the function name and its signature?

function addTwoNumbers(a, b) {

If so, then maybe a summary is OK to skip 👍

Parameters

Note — This is an important part of populating editor autocompletion

@param {type} name [- optional summary]

In short, what does this function expect me to pass along when I call it?

Data types are particularly important to me here: I can read through the code to figure out that foo could be a string, or an Object, or an instance of Foo, but it's a lot faster and more reliable to see it documented all in one spot:

@param {string|Object|Foo} foo

(In many, many cases, the variable name is self-documenting. In that case, I think it makes a lot of sense to skip the summary!)

Return Values

Note — This also helps populate editor autocompletion

 * @return {type}
 */

What should I expect when I call this function? An array? A Promise I need to await? Nothing at all?

Again, this is something you can glean from reading over the code, but (in my opinion) relying on that exclusively would tend to decelerate our overall velocity rather than accelerate it.

Personal Notes

I have two snippets in my text editor to make building out a JSDoc block quick and easy:

/** →

/**
 * @param {type} name
 * @return {type}
 */

and @param →

@param {type} name

to quickly add additional @param entries.

[desandro]

TODO Sandy - add writing JSDocs to the UXE Styleguide