On Thu, Feb 16, 2012 at 11:02 PM, Bodoh John Robert <[email protected]> wrote: > > I agree completely. Why doesn't the rest of the world agree and adhere to > this philosophy?
I don't think the disagreement is about that. As stated, the goal is to have *relevant* comments in the code. There's lots of reasons why this does not happen in real life. Eg - copy and change code, forgetting the remarks - use of boiler plate comments that don't get updated - the code was obvious the first hour after you wrote it - testing may reveal coding errors, but not incorrect comments - those doing peer review, is code rejected due to wrong comments? Having no comments is sometimes better than having wrong comments. In many cases no comments is better than trivial ones. When it's there it may disrupt the concentration needed to read the program (especially with "funny" remarks). The quoted BALR R3,0 is cute, but in my experience its often the opposite: LA R4,9 Set R4 with 9 or MVC ABCDATE,XYZDATE Copy date into ABC block ... MVC ABCTIME,XYZTIME Copy date into ABC block Only careful study of the code (and update logging) will reveal whether the code or remark is wrong (if any). Somewhere in this thread I suggested that remarks should be about the *why* rather than *what* of the instruction. Dave Cole's neat paper shows mostly "why" remarks. From browsing my inheritance, I think most repeated remarks (as written, not generated by macros) tend to be *what* and my experience is that the *what* more often is invalidated by code changes and bug fixes. Rob
