3 ms·
Really? So if a fundamental assumption changes in the code you'll be happy to make a 3 line change and rewrite 10 pages of documentation inline? Personally I
by loewenskind 16y ago
Really? So if a fundamental assumption changes in the code you'll be happy to make a 3 line change and rewrite 10 pages of documentation inline?
Personally I like the code to be as self documenting as possible about the "what", the check ins to be as explicit as possibly about the "why" (and "who" and "when") and documentation for architectural information ("where").
- DougWebb 16y agoWhile 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.