This argument is old and tired. Programming languages are rarely sufficiently expressive as to document the nuances, guarantees, and expectations of a particula

This argument is old and tired. Programming languages are rarely sufficiently expressive as to document the nuances, guarantees, and expectations of a particular block of code in the code itself. Type systems can help here, but they alone are not sufficient. An often stated rebuttal to the above is that the developer can comment the "complicated bits", and save time by skipping it the rest of the time. This is a flawed argument -- you don't know if you need to write a comment for a block of code until you've spent the time fully considering what needs to be commented ... which takes just as long as writing a comment. This holds doubly true for APIs. Any time that your future API clients spend reading your source code instead of skimming your documentation is wasted time. Additionally, deriving guarantees and invariants from the source code does not make them true -- the invariants could be changed in the future, as there's nothing in the code to document what should be, instead of what currently is. "Comments are unnecessary" is just an excuse for lazy developers to be lazy, and thus leverage externalities to reduce their upfront workload in exchange for increasing the workload and complexity for the programmers that follow them -- which may, in fact, be themselves.