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
Aren't you able to read the function implementation where should be some kind of documentation about which args it needs and which output it throws?
Something like:
/*
* The includes() method determines whether an array includes a certain value among its entries, returning
* true or false as appropriate.
* Parameters: searchElement (The value to search for), fromIndex (Optional; The position in this array at
* which to begin searching for searchElement).
*
*Note: When comparing strings and characters, includes() is case-sensitive.
*
* Return value: Boolean
*/
"Self documenting code" without typing any documentation like this is even worse than the lack of strong static typing on big projects.
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.
Aren't you able to read the function implementation where should be some kind of documentation about which args it needs and which output it throws?
Something like:
"Self documenting code" without typing any documentation like this is even worse than the lack of strong static typing on big projects.
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.