Even in situations like that one, I think it's possible to avoid the comment:
- setting up a type (with a comment linking to that API's documentation)
- setting up a shape validator & a test that asserts that that that field is a string with the correct shape
- Using a variable name that makes it clear that something intentional is happening: `const weirdlyStringifiedJSONObject = JSON.stringify(...)`
A comment might still be the simplest thing to add, but it doesn't mean it's the only way to document that weirdness. Comments can be fragile compared to the same documentation expressed in code
I agree that these are all good things, but they cover the what and not the why. I find design documents useful to cover the why--something that results in a long comment in my experience is usually indicative of some non-trivial design decision.
- setting up a type (with a comment linking to that API's documentation)
- setting up a shape validator & a test that asserts that that that field is a string with the correct shape
- Using a variable name that makes it clear that something intentional is happening: `const weirdlyStringifiedJSONObject = JSON.stringify(...)`
A comment might still be the simplest thing to add, but it doesn't mean it's the only way to document that weirdness. Comments can be fragile compared to the same documentation expressed in code
[edit: list formatting]