I agree that you shouldn't document "how", but when I'm reading unfamiliar code, I find I what I miss is "what", not "why". To my mind, in well-written code ea

I agree that you shouldn't document "how", but when I'm reading unfamiliar code, I find I what I miss is "what", not "why". To my mind, in well-written code each function should be documenting its contract: what it assumes, what it guarantees if that assumption holds. (And if it turns out that what you'd write is just the function's name and its parameter and return types with a few grammatical particles added, maybe it's OK to omit the documentation.) Then if you find that in order to do that you have to write a little essay, or you need terminology that doesn't correspond to a named thing in the codebase, or you're repeating yourself in multiple comments, that tells you something you need to put in higher-level documentation.