3 ms·

Someone reading the code should also be capable of understanding the problem that it solves and documenting the use of the code. If your code is fairly well wri

• bruce511 3y ago
  Code, like say English poetry, can be subtle. Reading the code can easily answer the question "what does this do?", but it usually doesn't answer "why are we doing it?" Most importantly it doesn't tell us what we're not doing here, and why not. I find myself adding comments to my own code when 6 months after the fact I'm re-discovering why something that looks casual is really important. Why that one "obvious " improvement or optimization is -not- done. But that's documentation at the lowest level. Most of my documentation time (and I'll admit to writing a lot of docs) is about a bigger picture; hoe is the code used, what problems does it solve, how it interacts with the world and so on. Documentation is not about writing the obvious "this increments x", its about making the code reusable, making it useful to yourself and your colleagues, my noting that it exists. It I'd if you like the "search index" into the code.