OpEd: Why to jsdoc Comment

WARNING: Until someone else says so, the only person who's behind what's written here is @knod. Input welcome.

Why Generate Docs from Comments?

Note: If you're working alone and/or on a small/simple code base, generating docs from function descriptions, etc, is probably overkill.

I've experience a lot of push back on documents generated from comments in code. Purely handcrafted documents seem to be the only way of doing things in many of the conversations I've had. I've asked about those objections and haven't heard a lot of reasons. I've personally found it pretty useful and convenient.

Purposes of Handcrafted Docs

Handcrafted docs are good for outward-facing information. They can tell people why the tool exists, it's goals, and how to use a tool or set up the environment. They can talk about the reasons behind major choices. They can be for guides, tutorials, and some kinds of examples. If you don't need anything too special, you can generate them with jsdoc too.

Handcrafted Cons

Sorry there are no counter arguments for these. The initial writer of this document had trouble seeing the other side.

Brain Juice

People lose brain juice when flipping back and forth between windows. For some people it's not a lot. For some people it is. Some people are lucky and have multiple screens, but that's not everyone. This is not saying that it's a major problem for anyone, but there are at least a couple of us out there that find that switching between a browser documentation window and working with the code is painful. It's slowed folks down, caused more error and confusion, and generally been obstructive.

Duplicate work

Given the first item, notes in the code are necessary, whether they're used for documentation or not. That means that de facto docs and actual docs have to be updated in two places - the code and the documentation files - and that's tedious. They'll get out of sync fast and there's more room for errors.

Updating

People who are bad at updating documentation are always going to be bad at it and their docs will be the opposite of helpful. It doesn't matter where those docs are - in the same file as the code or in another file altogether. Some of us find that we're much more likely to update the documentation if it's right there in the code as we're changing behavior.

Kills hope

At least some folks have seen that people generally don't read documentation when working in a code base (as opposed to using a separate API). It does seem unlikely, but we hope that if the comments are near the code itself those people are more likely to catch something out of the corner of their eye when they're skimming the code. It could be a prop name or a type or anything else. If the documentation is in a whole other place, there's no chance of that at all.

Purpose of In-Code Docs

Using in-code commenting to generate docs is for internal documentation. It's there to tell an active coder what some code does, how it works, and any unexpected behavior to watch out for. There are other reasons. See the guide on when to use jsdoc comments.

In-Code Cons

Quickly Out-of-date

This is the argument I've heard most often - they'll go out of date really fast. For counter arguments, see previous notes about updating above.

Write clear code instead

Code should be its own documentation. You should write code clearly enough that no further documentation is needed. Counter arguments:

1. Sometimes you don't want to read the specifics of the code just to find an answer to a broader question. Maybe really, really well written code can completely cover that problem too, though.
2. Code clarity is subjective. Having some more descriptive human-language details from a different angle might be useful when one person's very clear code is confusing to another person.
3. What if you're just not that good yet? Should you not write any code until you're that good? Theoretically, some people might be able reason about coding from the start without the need for such crutches. Even if they don't know coding well, they can leave their code un-commented and, though it'll be more work, they can still make forward progress. Others have experienced the need for some mental save points to hold their ideas in place while they look for the way forward.
4. If you want to collaborate, it's still a good idea to have some place where your code is documented. A website generated by things like jsdoc can be easier to look through than all your files.

Comments are a crutch

This is one I haven't heard, but that seems reasonable. It's an argument against comments in general. i.e. If you use comments to document/explain your code, you get lazy and write worse code because you figure you'll just explain it in the comments. I could understand that perspective and appreciate it, but if someone does make that argument I'd like to hear about specific experiences and/or research. Counter arguments:

1. See a lot of the stuff in the write clear code section.
2. Are there example of this happening? Maybe the coder would would have gotten (or already was) lazy anyway and comments didn't have anything to do with it.
3. Making comments is actually one of the ways I've learned and improved. It's given me a place to think critically about my code.