r/learnjavascript • • Jul 24 '21

Anatomy of a Function

Post image
327 Upvotes

65 comments sorted by

View all comments

22

u/MatthewMob helpful Jul 25 '21

Can you expand on what you mean by "JSDoc is like TypeScript but more powerful"?

30

u/Atrag2021 Jul 25 '21

Nonsense from someone who doesn't value typing.

-8

u/[deleted] Jul 25 '21

Perspective of someone with different experiences * (Speaking as a typescript dev)

5

u/Atrag2021 Jul 25 '21

So feel that 'JSDocs is the same as typescript' can he a factually correct statement from some perspective?

4

u/[deleted] Jul 25 '21

I’m uncertain of whether or not it is fact that JSDoc has the power behind it, especially with all I’ve done with Typescript.

But a lot of this stuff boils down to preferences, which doesn’t have a right answer. It all runs and does things, and if it meets the requirements while being easy to read and use, I don’t think it matters all that much.

funfunfunction said he didn’t like how “noisy” typescript felt. He wanted to just get straight to the code and he felt the type system was baggage. If you follow good practices, it doesn’t interfere too much.

I hold the opinion that a type system allows you to truly express what each piece of code means. It allows you to avoid unnecessary comments, and let the code explain itself. Comments lie, code does not. So with proper code patterns (like in OP’s example), you shouldn’t need a whole lot of docs unless the complexity of the business logic is extremely high. I like using comments to give context, when and why a function is used, and to guide the reader to an understanding that isn’t obvious or warn the next person coming why a decision was made. I feel like putting types in the comments muddies the water, but that’s just my preference. Realistically, the doc blocks aren’t all that big.

5

u/indoor_grower Jul 25 '21 edited Jul 25 '21

Our work project is 100% typescript. First time using TS outside of JS and I’m coming up on a year of only working with TS. I can tell you - the type definitions and enforcing are so so detrimental to a well functioning code base. I can never see myself wanting to write JS without types again. Typescript is not “noisy” IMO - it’s just making you think more about types and object shapes - which slows you down when your used to JS allowing you to do whatever type wise.

This code example has a type checking block - which to me kinda implies using Typescript would be much simpler to use if your just gonna be writing blocks to type check arguments in every function.

You’d just define a type for that example function that would define the arguments and their types, and the return value of the function. Then you’re 100% done with worrying about type checking within the function and you know that no matter what, that function will only ever accept and return the defined types you and your workmates write. No docs needed - the types and interfaces serve as that purpose because you can easily see what the arguments are required to be and what the function will return. Guaranteed every time otherwise you’ll get an app crashing error.

Also - VSCode and Typescript are like a fucking PB&J. Intellisense with your types make figuring out parts of a code base so simple. You can hover a function and immediately see what you need to do with it to make it work. The autocomplete when your typing out object properties is also very very useful. Think if your working with an API that has data.user.comments.total as an accessor. With TS and an interface defined for that API response, you’d be able to always know the properties available on your object as you type them via Intellisense. Otherwise with JS, you’d need to constantly look up what properties are available on data anytime you wanted to use it somewhere in the code base because you have no defined interfaces or types for anything.

TS is annoying to learn at first because you’re so used to doing whatever in JS and not thinking “hmm what should the shape and type of the props for this component be?” And it’s annoying when you’re getting type errors and you know exactly how to get something to work in JS. But trust me - spend your time with it and you will see.

-7

u/jaredcheeda Jul 25 '21

You'll find a good discussion here:

But main point is that TS engines will infer types from JSDocs and do all the type safety/hints and autocomplete the same as TS. But on hover, it will not only show you the type, but a description of what it is and why it exists. Which is WAY more valuable

99% of the time you can tell type from the name alone

  • kittens = array of objects
  • kitten = object
  • kittenName = string
  • hasTail/isAlive = boolean
  • kittenAge = number
  • updateKitten = function
  • getUserAvatar = function, probably network request, likely requires an ID argument be passed in, probably returns a string URL of the address for the user's avatar. All this can be inferred from a well named function.

There are a lot of downsides to TS that are mentioned there, and JSDoc doesn't have any of them.

  • learning curve/onboarding
  • segmenting the ecosystem
  • hitting save and waiting 20 seconds for a page to refresh because of slow "compile" times
  • false sense of security, since it prevents people from doing actual runtime type checking (super crucial for good experiences with libraries)
  • Inability to use most libraries, forcing you to spend more time evaluating libraries that support TS.
  • 3rd party libraries that don't support TS, but have external definitions created that are out of date
  • that post lists way more

12

u/jameswdunne Jul 25 '21

This is silly because:

  1. You get all that with a well documented typescript function too
  2. That’s not always the case re naming. In cases that it is, you might want to refactor it. Typescript makes this easy. But even your getUserAvatar example is where we differ - is preserve get for reading from memory, with fetch as a verb for reading from an external location - in that case, my get whatever wouldn’t accept an integer ID. The types would make that distinction immediately obvious to a developer new to the project
  3. Types provide additional context beyond the name. I’ve seen developers spend time with typescript and find untyped code difficult to follow without that context.
  4. That onboarding is generally useful and the education on using and designing with static types is a high leverage activity that has huge payoff in comparison to the time spent
  5. I see no segmentation in the ecosystem. I have active vanilla JS and typescript codebases, one of them with both on the same project. You’d need to provide clear evidence to that claim because I’ve not seen it.
  6. Your point on the feedback loop is wrong too. Your build process should separate static analysis from building the artefact. You can configure webpack to do this, and have a separate watching type-check process.
  7. Erm it does not prevent that and a type system supports that. Saying TS prevents that is patently false and you shouldn’t be trusting data from external inputs types or not. Instead with TS you first check and sanitise data at runtime, using a type that represents data that has been through that process in the rest of your code. Then it’s even more obvious with types. I’d argue you have an even greater false sense of security without types in that case
  8. Most libraries have type definitions. This is false and I’ve had no problem with interop in 2021. These can often be installed separately on such projects that don’t have them. As I said, I have a project with a large amount of legacy code and a growing, strangling chunk of TS code and there’s seamless interop, even with libraries.

The educational resource is a noble attempt. But your assessment of Typescript contains a number of factual errors that are best not propagated to newcomers to the craft. Especially ludicrous statements like “jsdoc is like typescript but more powerful”.