Guide: When to jsdoc Comment

If you're wondering why we generate some of the docs instead of writing them all by hand, skip to Purpose of In-Code Docs.

When to Make a jsdoc Comment

'Future coders' are either us in the future, or other people who read through the code or take on the project.

1. It isn't super easy to tell what a class or function is doing and/or how to use it.
2. Major code structures - it's the kind of thing you'd export or it's something like a method of a class.
3. We're describing some feature or improvement that would be good for future coders to think about.
4. It's something that's important for future coders ask/answer/think about/do.
5. It explains why we're doing things the way we're doing them - what secret info we had, what crucial info we were lacking, some very uncommon behavior of a language, other reasons that are hard to see.
6. We did something that wasn't great and the code is confusing, but we couldn't figure out how to make it better so now it needs extra explanation and a plea for forgiveness. Things like a lot of parameters, weird state objects, etc.
7. Sometimes when we're giving a link to useful information.

When to Make a Regular Comment

1. We're walking through code behavior happening inside the function, class, method, or object.
2. We want to remember to tweak or discuss some behavior in the code with each other. It'd be better to make issues out of those sometimes.
3. In the flow of the code, we're citing a specific item number in another document, like in a cfr (regulations) document. Whether that should actually be for jsdoc may be worth discussing, though.
4. We came up with a really funny joke and we're sure everyone else will rolf.