100% agree that documenting the "why" is something that you can't always do in code. Also, Ben Halpern makes an excellent point that avoiding documentation rot is an important reason not to document the "what" if you can avoid it. Also, I've used Elixir's commenting extensively and can say that it feels wonderful + natural to use doctests!
This makes me think of DHH's first writing software (well?) video. He spends 15 minutes discussing the rationale for removing a comment and replacing it with a better-named variable, which then becomes a well-named constant, which then gets placed into a more appropriate location in the code. It's an interesting thought experiment to say, for example, "could I simply replace this comment with a helpfully-named variable?".
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.
100% agree that documenting the "why" is something that you can't always do in code. Also, Ben Halpern makes an excellent point that avoiding documentation rot is an important reason not to document the "what" if you can avoid it. Also, I've used Elixir's commenting extensively and can say that it feels wonderful + natural to use doctests!
This makes me think of DHH's first writing software (well?) video. He spends 15 minutes discussing the rationale for removing a comment and replacing it with a better-named variable, which then becomes a well-named constant, which then gets placed into a more appropriate location in the code. It's an interesting thought experiment to say, for example, "could I simply replace this comment with a helpfully-named variable?".