5 ms·

I lived in the C# world for a while and our style guides mandated that we use those JSDoc style comments for every function definition. I loathed them. They inv

by jnsie 2y ago

I lived in the C# world for a while and our style guides mandated that we use those JSDoc style comments for every function definition. I loathed them. They invariable became a more verbose and completely redundant version of the function definition. Developers even used a tool (GhostDoc, IIRC) to generate these comments so that CreateNewUser() became // Create New User. Nobody ever read them, few ever updated them, and they reinforced my hunch that a small percentage of comments are useful (in which case, by all means, use comments!)

einpoklum 2y ago
I'm a library author and maintainer, in C++ rather than C#. I know what you mean about the redundancy, and my solution to that - which, of course, requires management approval in your case - is the following: 1. It is legitimate to skip parts of a doxygen/JSDoc comment (return value, parameter description) if it is _entirely_ trivial. But: 2. You must document the _why_. Well-written function signatures can tell you the "what", but they usually not tell you the "why". 3. You must make an effort to squeeze that non-triviality of a documented aspect. So, you mention corner-case behavior; you relate the use of a parameter to its use elsewhere; and of course - you describe "why"'s: Why that parameter is _not_ of another type, or why it can't be avoided. I guarantee you, that if you follow rules (2.) and (3.), you will usually not get to apply (1.); and at the same time, your doxygen comments will stop being annoying boilerplate that you automatically gloss over, because you would be much more likely to find useful information there.
- rerdavies 2y ago
  Could you provide an example of a function or argument type that needs a 'why' explanation. Not getting it.
  - skydhash 2y ago
    Not GP, but here is an example of one: https://git.sr.ht/~delthas/senpai/tree/master/item/ui/buffers.go#L97 https://git.sr.ht/~delthas/senpai/tree/master/item/ui/buffer... It’s mostly done to mark contentious, complicated, or good enough implementations because after reading the code your first reflex would be: Why is it done that way? Also personally I mark part of the code with short What? or How? comments for quicker scanning especially if the syntax is terse or it’s not immediately obvious. Kinda like a table of contents.
    - rerdavies 2y ago
      lol. Fabulous comment! I entirely understand the use of why comments in the body of code. I was more curious about why GP thought that functions and parameters should always have why annotations (and only have why annotations). Which seems a bit monstrous, unless I'm misunderstanding something.

by jnsie 2y ago

einpoklum 2y ago

I'm a library author and maintainer, in C++ rather than C#. I know what you mean about the redundancy, and my solution to that - which, of course, requires management approval in your case - is the following: 1. It is legitimate to skip parts of a doxygen/JSDoc comment (return value, parameter description) if it is _entirely_ trivial. But: 2. You must document the _why_. Well-written function signatures can tell you the "what", but they usually not tell you the "why". 3. You must make an effort to squeeze that non-triviality of a documented aspect. So, you mention corner-case behavior; you relate the use of a parameter to its use elsewhere; and of course - you describe "why"'s: Why that parameter is _not_ of another type, or why it can't be avoided. I guarantee you, that if you follow rules (2.) and (3.), you will usually not get to apply (1.); and at the same time, your doxygen comments will stop being annoying boilerplate that you automatically gloss over, because you would be much more likely to find useful information there.

rerdavies 2y ago
Could you provide an example of a function or argument type that needs a 'why' explanation. Not getting it.
- skydhash 2y ago
  Not GP, but here is an example of one: https://git.sr.ht/~delthas/senpai/tree/master/item/ui/buffers.go#L97 https://git.sr.ht/~delthas/senpai/tree/master/item/ui/buffer... It’s mostly done to mark contentious, complicated, or good enough implementations because after reading the code your first reflex would be: Why is it done that way? Also personally I mark part of the code with short What? or How? comments for quicker scanning especially if the syntax is terse or it’s not immediately obvious. Kinda like a table of contents.
  - rerdavies 2y ago
    lol. Fabulous comment! I entirely understand the use of why comments in the body of code. I was more curious about why GP thought that functions and parameters should always have why annotations (and only have why annotations). Which seems a bit monstrous, unless I'm misunderstanding something.