I'd argue that this adds extra maintenance as you have to ensure the documentation matches up to the implementation. There's no way to enforce the two to stay in sync.
At least with something like typescript you can't change the implementation without the types being updated/corrected.
This is kind of the whole point of self-documenting code regardless of typescript. With comments you have to remember and be responsible for updating the comments whenever you change any kind of implementation detail. It'd only take a quick hotfix or two developers working on different features, and the comments can so easily become outdated.
This of course is assuming that your third party javascript libraries even bother to write jsdocs for their functions. If you use a library with no jsdocs and no ts definitions, you're forced to refer back to the actual documentation, and no dev worth their salt ever actually reads the docs right? 😂
Tech Lead/Team Lead. Senior WebDev.
Intermediate Grade on Computer Systems-
High Grade on Web Application Development-
MBA (+Marketing+HHRR).
Studied a bit of law, economics and design
Location
Spain
Education
Higher Level Education Certificate on Web Application Development
I can agree and disagree with some points. Reading the documentation makes your work more efficient and reliable. You can use multiple functions you entire life without even knowing they have optional params that can save you some good time, i've seen that many times hahaha
Overall this is a fascinating debate that probably doesn't have a 'right' answer but I wanted to add to this 'write docs or don't' point. Writing documentation helps me clarify that I've built what I wanted to design. Sometimes I do it first as a rubber duck exercise and I always gain something from it when I do.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
I'd argue that this adds extra maintenance as you have to ensure the documentation matches up to the implementation. There's no way to enforce the two to stay in sync.
At least with something like typescript you can't change the implementation without the types being updated/corrected.
This is kind of the whole point of self-documenting code regardless of typescript. With comments you have to remember and be responsible for updating the comments whenever you change any kind of implementation detail. It'd only take a quick hotfix or two developers working on different features, and the comments can so easily become outdated.
This of course is assuming that your third party javascript libraries even bother to write jsdocs for their functions. If you use a library with no jsdocs and no ts definitions, you're forced to refer back to the actual documentation, and no dev worth their salt ever actually reads the docs right? 😂
I can agree and disagree with some points. Reading the documentation makes your work more efficient and reliable. You can use multiple functions you entire life without even knowing they have optional params that can save you some good time, i've seen that many times hahaha
Overall this is a fascinating debate that probably doesn't have a 'right' answer but I wanted to add to this 'write docs or don't' point. Writing documentation helps me clarify that I've built what I wanted to design. Sometimes I do it first as a rubber duck exercise and I always gain something from it when I do.