5 ms·

While I love a standard for API documentation, these kinds of documentation is seldom of use for me when I read code, it is usually the same boiler plate you se

by emj 4y ago

While I love a standard for API documentation, these kinds of documentation is seldom of use for me when I read code, it is usually the same boiler plate you see in this cheat sheet: "X a number". Git commits are ment to be similarly short there it is the what and why, in code I often feel you need the why and how, rather than what for function arguments.

alexose 4y ago
I feel the same way. Maybe it's because I came to programming in a roundabout way (i.e., no formal training), but I just see JSDoc-style annotations as wasted characters. Again, maybe just me. But, my brain doesn't parse them unless the code is already extremely well structured. In which case, why include annotations at all? Or in other words, isn't it always better just to improve the readability of the function itself?
- gl-prod 4y ago
  They aren't really designed for your brain to parse them; they help your IDE understand quickly what's happening.
29athrowaway 4y ago
If I could downvote this a million times, one click at a time until my mouse button stops working, I would. Documentation tags have a machine readable structure. That structure can be parsed and used for documents, editor hints, diagrams, and even type check validations. Instead of having to traverse the entire callgraph of a function to have an idea of what guarantees it provides, you simply read the documentation tag. This is O(1) instead of O(V+E) where V are the functions and E are how you call them.
- allendoerfer 4y ago
  > That structure can be parsed and used for documents, editor hints, diagrams, and even type check validations. > Instead of having to traverse the entire callgraph of a function to have an idea of what guarantees it provides, you simply read the documentation tag. > This is O(1) instead of O(V+E) where V are the functions and E are how you call them. Unless of course it is wrong, because it is just a convention for a comment and not actually an enforced type.
  - 29athrowaway 4y ago
    The right direction is: more explicit information, more commitment on a stable contract with explicit guarantees, maximize machine readability. The wrong direction is: less information, no stable contracts, forcing people to guess, complete chaos and anarchy, make up your own format with your own tags that nobody supports.
    - allendoerfer 4y ago
      We are on the same page, which is why I would advise to use TypeScript instead of JSDoc.
      - 29athrowaway 4y ago
        When you can use it, you should. My comparison was between: - JavaScript with no documentation tags - JavaScript with non-machine readable documentation - JavaScript with documentation tags
kjksf 4y ago
JSDoc provides type annotations in comments. They are (mostly) not for you. They are for the tooling, including your editor, to detect that your declared foo(bar: string) but you're calling it as foo(5). The value of JSDoc is the same as value of TypeScript: add static types to your code to detect bugs. And yes, it works in practice. I started using JSDoc quite recently. I don't enjoy adding those type annotation comments but undeniably they (and VS Code tooling, jsconfig.json) detect errors that, if not fixed, would end up blowing up at runtime and causing me to spend more time fixing them.

by emj 4y ago

alexose 4y ago

I feel the same way. Maybe it's because I came to programming in a roundabout way (i.e., no formal training), but I just see JSDoc-style annotations as wasted characters. Again, maybe just me. But, my brain doesn't parse them unless the code is already extremely well structured. In which case, why include annotations at all? Or in other words, isn't it always better just to improve the readability of the function itself?

gl-prod 4y ago
They aren't really designed for your brain to parse them; they help your IDE understand quickly what's happening.

29athrowaway 4y ago

If I could downvote this a million times, one click at a time until my mouse button stops working, I would. Documentation tags have a machine readable structure. That structure can be parsed and used for documents, editor hints, diagrams, and even type check validations. Instead of having to traverse the entire callgraph of a function to have an idea of what guarantees it provides, you simply read the documentation tag. This is O(1) instead of O(V+E) where V are the functions and E are how you call them.

allendoerfer 4y ago
> That structure can be parsed and used for documents, editor hints, diagrams, and even type check validations. > Instead of having to traverse the entire callgraph of a function to have an idea of what guarantees it provides, you simply read the documentation tag. > This is O(1) instead of O(V+E) where V are the functions and E are how you call them. Unless of course it is wrong, because it is just a convention for a comment and not actually an enforced type.
- 29athrowaway 4y ago
  The right direction is: more explicit information, more commitment on a stable contract with explicit guarantees, maximize machine readability. The wrong direction is: less information, no stable contracts, forcing people to guess, complete chaos and anarchy, make up your own format with your own tags that nobody supports.
  - allendoerfer 4y ago
    We are on the same page, which is why I would advise to use TypeScript instead of JSDoc.
    - 29athrowaway 4y ago
      When you can use it, you should. My comparison was between: - JavaScript with no documentation tags - JavaScript with non-machine readable documentation - JavaScript with documentation tags

kjksf 4y ago

JSDoc provides type annotations in comments. They are (mostly) not for you. They are for the tooling, including your editor, to detect that your declared foo(bar: string) but you're calling it as foo(5). The value of JSDoc is the same as value of TypeScript: add static types to your code to detect bugs. And yes, it works in practice. I started using JSDoc quite recently. I don't enjoy adding those type annotation comments but undeniably they (and VS Code tooling, jsconfig.json) detect errors that, if not fixed, would end up blowing up at runtime and causing me to spend more time fixing them.