I like TypeScript for its types and type-checking, but I also want to write JavaScript to avoid having a local build step, and having to wait for things to transpile/compile/etc when running locally. I have a pretty large project where I’ve gotten both worlds by just using JSDoc and only using TS for type-checking. VSCode still offers built-in type-checking with JSDocs and ofc the type-checking can also be run separately if needed.
Let’s face it, such comments usually cause more problems than do good. If someone changes the code and forgets to modify the comment, the reader might favor one or another at random. “Stop sign” example isn’t the best but you get my point.
Comments at best should explain some non-obvious logic, or some sort of reasons for implementing one way or another. For SDKs and packages overall, public APIs should also be commented. The rest imo should be readable from code.
A form of “self documentation” I like to do is create variables for conditions before using it in an if statement. If you break down a funky conditional into easy to read variables it becomes a lot more clear what it’s trying to do.
If someone changes the code and forgets to modify the comment, the reader might favor one or another at random.
Hence why you should comment why, not how/what.
// slow down traffic before crossing busy main road
Now you can change the stop sign to a yield without touching the comment. Or judge that the comment can be removed if it’s clear the main road does no longer exist.
I would hope it modifies the original. It’s implied in the name. A function that returns all but the first item should be named something like tail or without_first_item.
I put Haskell as last language on my CV, despite it being the language I’m most comfortable with and genuinely like, just because I don’t want to be “that” guy
EDIT: I’ll never put TI-84+ calculator ASM on my CV, but damn, I’m proud I knew it in secondary school
Yeah, it was fun until it was a huge project. I even was tutor in a lecture about Haskell and SQL once even though I hated SQL. Now I tell people in my job interviews what a great SQL tutor I was
programmer_humor
Top
This magazine is from a federated server and may be incomplete. Browse more on the original instance.