As a backend programmer, I really thought I had this nailed. I'm good at writing clean, mostly-pure code that composes well. The idea is to get the code to the point where the "what" and the "how" is communicated (clearly; avoid cleverness whenever possible) by the code itself, and to save the comments for the "why". That way if the "why" gets out of date, you can revisit whether that code should be there at all. The exceptions should be the highly tuned code that is hard to read - documenting what/how is more appropriate there, and that code should rarely change anyway.
But all that started changing with react hooks on the frontend. With contexts and state going everywhere, it's really hard to document. How do you document a state machine that by definition is spread between multiple code locations? You can document a hook's purpose but it doesn't tell you anything about complex behavior. It starts to feel as hard as documenting code that has a bunch of mutable global variables.
But all that started changing with react hooks on the frontend. With contexts and state going everywhere, it's really hard to document. How do you document a state machine that by definition is spread between multiple code locations? You can document a hook's purpose but it doesn't tell you anything about complex behavior. It starts to feel as hard as documenting code that has a bunch of mutable global variables.