Yes. As described in the article, the TypeScript compiler understands type annotations that are written in JSDoc syntax. So you can use `tsc`, just like you would to check `.ts` files.
By "JSDoc is TypeScript", culi means "JSDoc syntax and TypeScript syntax are two alternative ways to describe types to the TypeScript compiler/language services, and the two syntaxes have nearly-identical expressive power".
I understood it that way too. Only that it fails in that interpretation.
Just because currently the most popular method for parsing JSDoc utilizes TypeScript-related tooling doesn't mean we should associate them with each other.
To my previous example, an ISO C++ can be compiled by GCC but also can be compiled by Clang (and many other compilers).
Perhaps I should've expanded further to "the specific JSDoc dialect supported by the TypeScript compiler and TypeScript syntax are two alternative ways to …".
Unlike ISO C++ I'm not aware of any standard for what JSDoc is outside of specific implementations. There's a bunch of stuff documented on https://jsdoc.app/ but it only partially overlaps with the JSDoc syntax that TypeScript uses, and is not what the article is talking about.
The situation is not unlike Markdown before the CommonMark standard (except with less pressure to standardize, because most codebases are written with specific tooling in mind). Maybe we should refer to it as "TypeScript-flavored JSDoc".
> IDEA adds its own analysis on top of that provided by the language server.
IDEA implements its own analysis and doesn't use tsserver at all. Its semantics diverge in subtle ways, I believe in both directions (some code that tsserver considers valid IDEA will consider invalid and vice versa).
Thanks for the example, I had a good play around with it.
The second part of my comment is a value yes, but it's implicitly typed by typescript automatically. I was asking about how to use that type (and it's internals) in jsdoc.
`test()` only returns a boolean, you want to look at `exec()` which returns the result of the regular expression (typed as: `RegExpExecArray | null` which you can narrow down to `RegExpExecArray` by checking if the result is null or not).
RegExpExecArray gives you a structure that looks different between the jsdoc version and the typescript version.
The typescript version has `.groups` inside RegExpExecArray.
You can use that as is, or you can add some extra type utilities to extract the named groups from inside the regex. (If you look inside typescript's issues on github you'll find a whole bunch of them that people have wanted typescript to include by default).
There's a few regex PRs to add extraction and syntax checking to typescript by default, but they're delayed until after the compiler switch from ts to go. (but there's porting to go in the PRs anyway).
Could you show me what you mean in the playground? You can change it to JSDoc mode by selecting "JavaScript" in the "Lang" dropdown in the "TS Config" tab.
Your examples has groups only typed as { [key: string]: string }.
It isn't narrowed down to the actual named capture groups inside the regex.
For the whole semver example, we'd want something typed as: { major: string, minor: string, patch: string }.
(sidenote for this semver example and not regex in general: they will be strings because a major of "01" and a patch of "3-prerelease" are both valid. You can parse them into ints later depending on what you're actually doing with the semver)
---
For an example of a type narrowed regex in the ts playground, I'll take the lazy route and point you to an example someone else has made:
You can use a utility library (e.g. ts-regexp, arkregex, etc...), you can use one of the utilities that are shared around the typescript spaces online for the one part you need, or you can make your own utility type.
---
For my use-case, I just want to know that I can change either my code or regex and I'll be alerted before runtime or buildtime if I've forgotten to account for something.
To carry on with the semver example, if a fourth piece of data was added to the incoming string (e.g. product name, build timestamp, build variant, etc...) and I forgot to update both the code and the regex together and instead only updated one, I'd want an alert in my IDE to tell me that I forgot to update the other one.
The behavior of ts-regexp is not especially related to the `RegExpExecArray` type. That package uses unsafe assertions to implement its API.
The only thing that requires TypeScript syntax in the playground you linked is the non-null assertions. Here's that same code in JSDoc mode with the non-null assertions removed (`strictNullChecks` is disabled instead): https://www.typescriptlang.org/play/?filetype=js#code/JYWwDg...
---
> For my use-case, I just want to know that I can change either my code or regex and I'll be alerted before runtime or buildtime if I've forgotten to account for something.
If you can show a concrete example what you want using TypeScript syntax then I'm pretty sure I could port it to JSDoc syntax. (To be clear I'd personally much rather write the TypeScript syntax as I find JSDoc comments annoying & verbose, but they're plenty powerful, being nearly isomorphic to TypeScript annotations.)
Generally, no. Only in the case you had a requirement to exclusively use JavaScript as the programming language you might be in for an awkward time justifying that you added type checking to the project via the type checker component of TypeScript with JSDoc :)
Depends on your definition of "using" JavaScript. The main difference between common TypeScript and TS-based JSDoc is the need for an additional build step. Being able to ftp-upload your `.js` files and then be done with it is a remarkable advantage over Vite/Webpack/whatever in small to medium-sized projects. If editor based type support is sufficient to you (i.e. no headless checks), you won't need to install any TS packages at all, either. tsserver is still used in the background, but so are thousands of other binaries that keep your editor, OS and computer running, so I don't see that as an argument.
I think this philosophy only reasonably applies behind the public-facing API gateway. So the GraphQL API server wouldn't be part of the microservice graph that you're trying to make into a polytree (you also wouldn't consider the client-side software to be part of this graph). You can use GraphQL delegation or similar to move more responsibility to the other side of the line.
The only alternative I can think of is to have a zillion separate public-facing API servers on different subdomains, but that sounds like a headache.
Maybe you meant "they can be anywhere that a Node can be in the DOM", but I think that's more or less what the CSS "mistake" is suggesting should be true about CSS (just replace "DOM" with "CSSOM").
I wouldn't say that, it's more that the CSSOM doesn't try to preserve comments, which is a perfectly reasonable thing to do. I think most uses cases for modifying CSS that care about comments (e.g. auto-formatters?) would need parsers that return the full CST anyway.
I see. I was under the impression that you were saying the "mistake" from the post was wrong in its premise. But I guess that's incorrect, rather you think that people shouldn't use the CSSOM for use cases when comments matter, and instead they ought to design their own parsers/representations.
Just curious: do you feel the same about HTML? Should HTML allow comments in more places? I can imagine alternate ways to represent an HTML document that could capture comments within attribute lists, etc (and the DOM could exclude them entirely).
Nah I think HTML comments are fine. I don't think there would be a benefit to allowing comments in more places and it would make it more annoying when you actually do want to process comments.
If CSS had mandated that comments could only appear in certain places (e.g. before a rule or attribute) I think that would have been fine too, though maybe slightly confusing given the resemblance to C-style comments which are allowed almost anywhere.
Seems like we have broadly-similar perspectives, though I do find it a bit incongruent that the DOM preserves comments while the CSSOM doesn't. It feels like they ought to be in alignment one way or the other (though I also understand the historical reasons why they aren't).
Ticket numbers are good enough as long as they don't rot (i.e. you never permanently delete tickets). That's just writing the "why" somewhere else instead of in the commit message; the important part is that it's written down somewhere and is discoverable/accessible to future folk (yourself included).
I like putting a minimal description in the message itself too so it's easier to skim the log, though.
That Google guide also says that the first line of the commit message should be a "short summary of what is being done". Is your complaint that 50/72 characters is too short? How long can it be before no longer meets the Google criteria, in your opinion?
Yeah, I specifically think 50 is too short. I am a big fan of brevity, but I think the sweet spot is somewhere around 100. Consider that all of these messages exceed the 50-character limit:
[startup] Don't drop uid until all controller fds are open
[bpf] Fix the exec exchange hitting verifier limit on Fedora
[controller] Optimize partial policy updates with delta
They're as short (IMO) as can be without omitting useful information, but git says they're all illegal by some margin.
I agree on the value of concise writing and dislike word salads, but if you're a junior engineer, then I have maybe 1 hour with you per week and I probably shouldn't spend that time being your English teacher.
I know I've seen some people recommend 50 (my guess is that's to make some room for metadata from commands like `git log --online` in an 80-column terminal?) but I've personally always capped all lines at 72, including the first. 100 seems like a reasonable limit too, but I probably wouldn't go above that.
> git says they're all illegal by some margin
Git will accept almost anything as a commit message. Is there a specific style guide you're referring to?
---
EDIT: Huh, I guess git does have an official recommendation. I'd never noticed this text in `git help commit`:
> Though not required, it's a good idea to begin the commit message with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more thorough description.
I wouldn't feel bad about not following this advice. Even the author doesn't seem dogmatic about it.
> if you're a junior engineer, then I have maybe 1 hour with you per week and I probably shouldn't spend that time being your English teacher
It's not important enough to make a big deal out of, but if I see it over and over from the same person I might mention it during code review ("your commit messages are a bit wordy; for example instead of '…', consider '…'") or write down as part of a style guide (e.g. if we're tagging commits like in your examples, wherever we wrote down the rules for that). It's the same for other unimportant things that it's nice to agree on (e.g. capitalization of initialisms in code—is it `.toJson()` or `.toJSON()`?).
I may be misunderstanding: are you saying a commit message with a 200-character-long first line could be an example of a "good" message to you/Googlers? To me that seems like something that could almost certainly be summarized further, regardless of how complex the changeset is (if not it's a sign the commit should be broken up into multiple simpler commits).
Can you give me an example of a commit where the "short, focused summary" can only be usefully-expressed in 200+ characters?
A good dev isnt necessarily a good writer. Summarising complexity concisely is difficult.
Restrictions lead devs to write to useless messages like 'fixed a bug' rather than messages that are slightly verbose but actually useful.
Most messages wont be 200 chars. But id rather 200 chars of useful text than 72chars of useless text.
The real world is full of average devs that are average writers under time pressure to deliver code. Expecting them to deliver above average commit messages like googles examples is a pipe dream.
Should this reasoning be applied to other skills involved in software engineering? If someone never writes tests, or over-architects everything, or has terrible people skills, or never updates documentation, or doesn't bring attention to blockers, or constantly forgets to update the issue tracker, or doesn't follow the local code conventions, or works on random tasks and ignores high-priority ones, etc etc etc the solution isn't usually "don't ask them to do a thing they're bad at", it's "help them get better".
The important question is whether "skimmable commit messages" is a thing you care about enough to advocate for and teach people about. Maybe you don't, and that's fine.
> But id rather 200 chars of useful text than 72chars of useless text.
I completely agree with this. I just don't think those are the only two options.
> Expecting them to deliver above average commit messages like googles examples is a pipe dream.
This thread started with praise for that Google guide and I assumed you were of similar opinion given your reply. That's why I kept referring to it.
1. I basically agree with everything you say, I only think the limit should be ~50-100% higher. Not 10x, but 1.5-2x.
2. For some reason, concise writing is the hardest thing to teach and demand consistently. I think a part of is that people try to hide incompetence behind a word salad, but also I think non-native speakers use more words than they need. It gets to a point where you either have to become everyone's English teacher or accept some amount of word salad.
reply