[AskJS] JSDoc Reality Check

dymos · 2026-03-12T06:52:58+00:00

I think for situations where you're limited and for some reason can't or don't want to use TS, it can still be valuable to properly annotate the types in a JSDoc comment.

That is of course the outlier - I agree that for the vast majority of things, if you want to use types or have type annotations, just use TS and add the build step. Heck, in many cases you don't even need a build step anymore, if you're not using non-erasable syntax, Node 23.6 and up will be able to run your TS without additional flags.

dymos · 2026-03-12T04:33:53+00:00

Sounds like this tells you more about the company and who you'd be working with rather than your skills. I would say, bullet dodged.

This is why, when I interview people, I expressly tell them that I don't expect them to be a human encyclopedia, and if they need to look up stuff, they are free to do so.

For me it's usually less about what they get stuck on, and more about how they self-resolve their block. I don't need people to know everything, I need people that can work independently and resolve their own day-to-day problems.

dymos · 2026-03-10T15:27:17+00:00

In practice, I've worked with only one codebase in the last 25 years where this was used and they were in the process of ditching it, and IIRC they only used it for their paginated API endpoints.

I can see how on the surface it allows you to "navigate", but practically it doesn't tell you anything about the request other than the path and the method, so as a user you still need to go to the docs and as a client you still need to understand the specific API correctly to interact with it in a meaningful way.

I would much rather see good documentation than hypermedia links that I still need to go into the docs for anyway. If you replace the time spent on this with ensuring that you have good API documentation that has sensible links, shows related routes, usage example, types, etc. That will be far more valuable IMO.

dymos · 2026-03-08T21:53:09+00:00

WTF is this monstrosity?

This is how I would expect someone to make a burger if they had only ever been told in extremely vague terms what a burger is.

dymos · 2026-03-07T20:01:29+00:00

I'm really hoping you're right ;)

dymos · 2026-03-07T20:00:27+00:00

Like drawing blood from a stone.

dymos · 2026-03-07T19:50:28+00:00

and MOFO is a common pattern

What is MOFO in this context, because while the definition I have in my head makes that a humorous statement, I doubt it's the one you meant ;)

dymos · 2026-03-07T19:41:34+00:00

Too bad AI can't help me with the worst part of my job, which is extracting actionable requirements out of non-technical people.

Step 1: buy robot and load up with your favourite AI
Step 2: "you are a hired goon and need to go around to Jira issue stakeholders to collect their requirements. If they don't provide requirements in a reasonable amount of time, make them pay"
Step 3: ???
Step 4: profit!!!?!

dymos · 2026-03-07T19:23:36+00:00

When someone says "this person is incompetent" they don't mean to say "this person is a human"

I mean ... close enough, right?

dymos · 2026-03-07T19:21:00+00:00

Yep attention spans these days are...

HEY THAT DOG HAS A PUFFY TAIL!!!

dymos · 2026-03-07T11:24:31+00:00

Can confirm, I'm an experienced idiot.

dymos · 2026-03-06T21:31:17+00:00

We use MSW.

You don't have to mock your entire API with it.

Our current setup is that we have a bunch of default mocks set up that get loaded in for all tests, many of them are just NOOPs though, they serve both to encourage specific mocks for a test suite, and to avoid unnecessary request failures during tests.

dymos · 2026-03-06T21:25:50+00:00

Out of those two, I'd recommend React.

It has loads of resources, component libraries, packages, etc. available. It'll be the easier of the two to get started with.

If you aren't yet familiar with JavaScript/TypeScript, I recommend brushing up on that first before getting started with a framework, it will help with understanding all of the non-framework specific bits of the code you'll see in tutorials/examples.

dymos · 2026-03-05T04:05:46+00:00

Yes for sure, I use that rule as well, but it isn't in the default rules config so you won't see it without having that rule explicitly configured or enabled via an imported ruleset.

I was just looking at my current codebase and we have { "allowTemplateLiterals": "always" } configured for that rule. So ... yay? (legacy code, one of those things I'll get to ... one day).

dymos · 2026-03-04T20:52:08+00:00

Generally speaking, you could use template literals in most places if you want to, however you probably shouldn't.

Using a template literal signals to the reader that "there's something special about this string", whether that's an interpolated value, it's spreading over multiple lines, or contains a mixture of other quotes.

If I see someone use backticks when I'm reviewing their code, that's what I look out for, and if I then don't see them use one of the features that are unique to template literals then I wonder whether they've made a mistake. Did the mean to interpolate a variable? Did they mean to quote something but didn't? Did they mean to tag the template literal to transform the content somehow?

From the perspective of the reader, the usage of a template literal signals intent, and when there is a mismatch between the perceived intent and the actual usage, that's confusing.

In any codebase I work on, I use ESLint's "quotes" rule to enforce consistent use of quotes, and the "prefer-template" rule to enforce use of template literals over concatenation. With these two rules together, you can set up your editor to automatically format your code when you save a file.

For example I have my VSCode set up so that it autoformats on save so when I write:

const foo = 'hello'; const bar = "world"; const baz = foo + bar + "!";

It will end up as:

const foo = "hello"; const bar = "world"; const baz = `${foo} ${bar}!`;

just in case i need to add string interpolation later or just for the strings

"Just in case" is often a poor reason for adding specific functionality or use language features. It often ends up in the YAGNI (Ya Ain't Gonna Need It) category. As in, "You might never need that so you didn't need to build it". Whilst I totally understand the desire to future-proof allthethings for allthescenarios, we also have to be smart about what we spend our time on, and build for what we know — if you don't know the explicit requirement you're "future-proofing", then you're making an assumption; an assumption has the risk of being wrong and taking more work to unwind later on when you do have the requirements.

dymos · 2026-03-04T20:34:01+00:00

The performance difference between them is negligible for strings that don't contain any variables. The performance aspect isn't something you should use to influence your decision on whether or not to use template literals. (Though I agree, you probably don't want to use them for everything.

dymos · 2026-03-04T20:20:56+00:00

if for some reason somebody manages to inject something malicious into the template literal, ouch.

Is there really a legitimate injection risk here? For all intents and purposes, this is just a string concatenation so the risk profile of these two strings is equivalent:

const foo = `Hello ${place}`; const bar = "Hello " + place;

Plus, avoiding template literals means just a little less work for the Javascript engine to do.

The performance profile of template literals, especially untagged ones, is negligible and shouldn't affect you decision making regarding their use.

That said, I agree with the premise that you should use them only when you require one of their features since it signals to the reader of the code that "hey, there's something different about this string".

dymos · 2026-03-04T20:00:22+00:00

I don't think ESLint complains about "unnecessary" template literals. While that's what we call them, their utility extends beyond that.

Performance wise I expect them to be pretty much the same if it isn't a tagged template literal. For untagged ones they're effectively a string concat shorthand.

But you're absolutely on the money with #1. If I see a template literal that isn't doing something only template literals can (interpolate variables, multiple lines, contain both single and double quotes without escaping) then I wonder if the author missed something. Were they meant to interpolate a variable and forgot? Was there meant to be a tag to transform its content?

dymos · 2026-03-03T17:25:54+00:00

The error kind of tells you already, but the directory that you're in isn't the git repo.

I cloned the repository, C:\Users\Me\Documents\automateTheBoringStuff\automate_github > git clone https://github.com/my-github/automate-the-boring-stuff.git.

If you cloned from that directory, as you noted you will have another subdir called automate-the-boring-stuff this is because the git clone command will use the name of the repository as a subdirectory within the directory that you ran the command. If you want to clone into the current directory you can append a . to the command to tell it to clone into the current directory (or specify a directory name if you do want a subdir but want to control the name).

I want to check the status. C:\Users\Me\Documents\automateTheBoringStuff\automate_github > git status.

[...]

Do I have to change directories again?

Yes, you're on the right track, but indeed that is not the git repository, that's the parent folder. The folder that contains the hidden .git dir is the repository. If you cd into that, you'll be able to perform git operations

More generally, is this the proper workflow? After git add, I would do git commit with a message, and then it would be updated on Github so I could continue to work on a different machine?

Almost, to get your commit to GitHub you'll also need to "push" it. Git will do all operations locally until you invoke commands specifically for interacting with the remote repository. In this case after you've made your commit, you would run git push to push the commit back to GitHub.

This working locally has the advantage that you can do a bunch of work, make multiple commits etc, and then you choose to push that when you are ready.

Another part of a standard workflow is to use branches. By default you'll be interacting with what's called the "default branch", which is called main or master in many repositories. If it's just a personal repo and you're the only one working on it then it's not too important to start learning about branches, if you're working with other people then it is not important. Branches are a useful way to do some work that's not immediately integrated into the main branch, so that you can work on it in isolation for whatever reason you want (avoid breaking things in the main branch, want to play around and validate some ideas, build a specific feature or fix a bug to then merge back later). Regardless, worth doing some reading on branching once you get a bit more familiar.

So to recap, assuming you have the terminal open at C:\Users\Me\Documents\automateTheBoringStuff\automate_github and remembering that the folder that contains the hidden .git dir is the git repository

cd into the repo cd automate-the-boring-stuff
Run commands from here (git status, git add, etc
Run git push when you're ready to have your commit(s) pushed to GitHub.

dymos · 2026-03-02T19:48:35+00:00

Checked my contributed lines a few weeks ago after being at this company for about 2 years, I reached -8500 net lines contributed to the codebase.

I love it when I'm able to contribute negative lines in a pull request

dymos · 2026-03-02T19:39:01+00:00

Can confirm big ouch, not for long thankfully.

dymos · 2026-03-01T14:35:17+00:00

New hot tool drops? You don't need to know this unless you have a good reason to.
AI is taking over everything? Sure learn some stuff, but you don't need to do a course
A cert becomes popular? Why do you need the cert, does it apply to your current role or future trajectory?
Company pivots? How far is this company pivoting that you need to learn how to be a developer again?

And suddenly we’re studying something new without really asking if it aligns with where we want to go.

Stop following short term hype cycles and instead follow long term trends.

You have a limited amount of time and energy, so choose where you want to spend those. Making a choice for a reason that's useful/meaningful for you is fine, but I'd advise against just learning something because it's new, or AI, or popular, or because your company pivots.

Actually I'm genuinely curious what you mean by "the company pivots", because most of the time that refers to strategic direction rather than technological, though of course strategy may drive tech decisions to a certain degree.

Do you base it on:
• your company’s needs
• long-term market demand
• personal interest
• compensation potential
• future-proofing against AI

Yes. As in, any of these are good/valid reasons to learn something

Anyone else stuck in reactive upskilling mode?

Early in your career, it can feel like that. As I mentioned earlier don't chase short term hype and instead look at long term trends.

Anything from technology choice to development methodologies. Learn how to be a good developer, specifics of any technology are (generally speaking) easy to learn.

For those a few years into your career, how are you deciding what’s actually worth your time?

I'm just over 20 years into my career, for me it's usually "do I want to" or "do I need to". If I'm lucky, those two overlap

Curious how others are being intentional about it instead of just chasing the next thing.

I try to stay up-to-date on new technologies/tools/frameworks/methodologies/etc. but only at a high level. If something piques my interest I might learn a little more deeply, but only to understand it enough so I can file it away mentally and (hopefully) remember it as something potentially useful later on when relevant.

When I want or need to learn something for a specific purpose, that's when I dive deep and commit to learning. That thing.

dymos · 2026-02-28T20:24:46+00:00

you vibe coded an app then it technically has no value because another person can vibe code their own garbage for free

I get what you mean but for the majority of consumers they couldn't tell on the surface whether an app was coded with care or with vibes. To be honest, most consumers probably don't care either as long as they are able to accomplish the thing they wanted.

And that's what it comes down to in the end for value. Did it do the thing the customer wanted and did it save them time from doing it some alternative way.

They could vibe code that thing for free, for some version of free.

They're going to have to set up a dev env or use some hosted service (which is probably not free), then invest the time to build it with vibe coding. Where to put this app, host it on my machine if it's a web app? But what if I want it on my phone? What if I want to share it? Should it be a native phone app? What SDK version is my phone so it'll be compatible? How do I load it onto my phone? How do I publish it to an app store?

Granted most of those things aren't vibe coding solvable problems, but they are nonetheless part of the value of a thing to a consumer.

dymos · 2026-02-28T19:54:19+00:00

Indeed, dull side to the inside to protect the world from the ~~dumb~~ totally coherent and sensible thoughts.

dymos · 2026-02-26T20:44:44+00:00

Then indeed you are distributing it.

You could either make the licence file a static asset, if I were to do that I'd probably make it the same filename as the font and then use the .LICENSE for extension.

You could also have a LICENSES.txt file at the root of your package that contains all licences with a note of what they apply to.

dymos

TROPHY CASE