While I agree with your second paragraph, I have to say that yes, I'd be happy to rewrite inline documentation to reflect a 3-line code change. Ten pages of inl

While I agree with your second paragraph, I have to say that yes, I'd be happy to rewrite inline documentation to reflect a 3-line code change. Ten pages of inline documentation is a lot and probably inappropriately located, but if it really takes ten pages to describe what three lines of code are doing, there is just no way those three lines of code can be self-documenting. (So much for extreme examples...) As you mentioned, there are different places for documentation: inline, commit comments, change tracking system, project/release planning documents, and overall system architecture documents. These all serve different purposes, describe different aspects, and typically have different audiences. They all have different levels of detail too. The code itself is the most detailed documentation, because it describes what the software actually does when it runs, and should be as readable as possible. The inline comments supplement that, because the code describes "what" but not "why". You mention that check ins should describe "why", but they give the why for the overall change, not for each block of code. Inline comments give the why for each block of code.