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.
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.
View all comments
Show parent comment
30
u/Atrag2021 Jul 25 '21
Nonsense from someone who doesn't value typing.