3 ms·

I see comments as sort of a fallback when I don’t have time or can’t think of a more readable solution to a problem. I believe this is the rational presented in

• deleted 8y ago
  [deleted]
• mannykannot 8y ago
  I think you you have identified the source for this dubious concept's widespread acceptance. Putting aside the question of whether this is only about comments -- the article is about documentation and the myth of self-documenting code -- suppose you have written a function. There are many things another programmer might want to know about it, such as its time complexity, whether it is thread-safe, what exception guarantees it provides (or simply what exceptions it might throw, and what they signify), whether it modifies state, and if so, when and what, whether its design is predicated on the system being in one of a subset of possible states... how much does a developer have to read to answer one of these questions? The answer is that, in general, it is not bounded. Now, the amount you would have to write to answer all possible questions is also not bounded, but -- and this is the real point -- you can choose what to document in order to maximize the usefulness of the function. And it is rare that the optimal solution is no additional documentation beyond the source code, at least for non-trivial components of non-trivial software.