Seymour J Metz wrote: >Nothing is wrong with a comment that elucidates the purpose of the >instruction. A comment that merely translates the instruction is worse >than useless.
>I can already figure out that the instruction will be executed; tell me >*why* in the comment. How does it fit in the broader scheme of things? >Where are the EX instructions and what is the significance of the >lengths that they use? I concur 100%, but find this hard to impart to people for some reason. I get responses like "Why would I comment a line like LR R4,R3?" and try to tell them, "WHAT are you moving? WHY? That's what I need to know when I read your code!" I consistently find that they don't get it. And so I get poorly commented code: lines without comments, and some with comments like "Move R4 to R3". I'm starting to suspect that we've crossed some threshold with code such that people have never inherited decently commented code, so they don't understand the value therein. That is, every time they've inherited something they've had to try to figure out what it does from the code itself. Once you've worked with well-commented code, you "get it", I think. And before someone asks the obvious: I'm not writing enough code these days to leave enough of a trail for folks, and the code I do write, I tend to get to fix/update. Maybe I should refuse to do so, force one of the other folks to update mine, see if the light goes on. Oh, and I don't give myself any credit for any of this theology: it was imparted by others upon me, starting at UofW when I worked in computing services. The z/VM CP code (HCP) is also a great example. ...phsiii
