I found it difficult to follow on many levels, probably because the author has been so frustrated that it became a really passionate piece. > When you write “s

I found it difficult to follow on many levels, probably because the author has been so frustrated that it became a really passionate piece. > When you write “self-documenting code”, it’s self-documenting to you. When documenting code, it is also documenting to you. Just as there is no way to predict what will be obvious and not when writing code, the same applied to documentation. We all had to wade through piles of documentation that means nothing to us because the person writing it has a completely different framing. That's not an argument for either side. > But even though comments are garbo, they’re still the only means we have of interleaving code with expressive human-to-human communication. A lot of people engaging in these discussion completely ignore that most of the code we write now is versioned, and switching on/off the blame display on a file is enough to bring a ton of context on any single line. And if it's not enough, just get back to the merge request with the explanations and the comments, eventually discussion of the whole feature. To me this currently the single best mechanism to switch from just following the code, to trying to get the context, when it was written, by who, for what ticket, for what release etc. It looks to me the whole "better documentation" the author is looking for is in that meta system that is not just versioning our code, but he doesn't seem to care to jump back and forth, and everything absolutely needs to be in his editor. That's pretty alien to me.