alt Hacker News> If good code was enough on its own we would read the source instead of documentation.
An axiom I have long held regarding documenting code is:
Code answers what it does, how it does it, when it is used,
and who uses it. What it cannot answer is why it exists.
Comments accomplish this.Replies
necovek • today at 7:13 AM
Good naming and good tests can get you 90% of the way to "why" too.
➕ show 1 reply
An important addendum: code can sometimes, with a bit of extra thinking of part of the reader, answer the 'why' question. But it's even harder for code to answer the 'why not' question. Ie what were other approaches that we tried and that didn't work? Or what business requirements preclude these other approaches.