I try very hard to put a cogent comment on each machine instruction and all USINGs and DROPs. And I add a paragraph or two at the beginning of small subroutines. I do this for two reasons: (1) I have spent a lot of time studying other people's code with either poor or no comments, and I don't want to inflict that misery on anyone else; (2) but I especially don't want to inflict the misery on myself, either, and I know from experience that within a month or two I will not remember why I coded certain things the way I did, and the comments help ME understand my own code, too. That's what enlightened self-interest is all about.
Bill Fairchild -----Original Message----- From: IBM Mainframe Assembler List [mailto:[email protected]] On Behalf Of Dave Cole Sent: Thursday, February 16, 2012 4:07 AM To: [email protected] Subject: Re: code comments and code maintainability Sorry to be late to the party. (I was vacationing in Vegas. Great show town!) A decade or two ago, I had a friend who didn't like to comment his code. When asked to, he would say "It was hard to write. Therefore, it should be hard to read!" That is a sentiment I have come to revile. John Gilmore wrote: >A comment like 'store registers' attached to an SR instruction is worse >than useless. Bernd Oppolzer wrote: >My favourite one is: > BALR R3,0 SUBTRACT 1 FROM R3 >Obviously, the opcode is wrong, should be BCTR. I really laughed out loud when I saw these. Contrary to the first poster's thesis, they both illustrate *perfectly* why even trivial comments are useful! WRT whether one should read the comments or the code (or even the object), it is ridiculous to read one and not the others. When desk checking, all three are important sources of information. To ignore one in favor of the others is a sign of laziness and is always a mistake. For example, when a comment contradicts the code, that is an important red flag that would be missed by anyone focusing only on the comments or only on the code. At 2/10/2012 08:52 AM, John Gilmore wrote: >Comments are or, better, should be of two sorts: > >1) Substantial prefixed blocks of text, often several hundred lines of >them, that describe what will be done and how it will be done, and >explicate coding conventions for parameters, and > >2) comments following single instructions, 'remarks'. I wholeheartedly agree with the general ideas here. These are the elements of good quality commenting, and good quality commenting is *essential* for writing good quality (and therefore maintainable) code. Several years ago I gave a paper at SHARE about this. It was titled "Considerate Programming: Reducing the Maintenance Costs of Commercial Quality Code". If you are interested, you can find it here: <http://www.colesoft.com/Articles/commercialqualityprogramming.pdf>http://www.colesoft.com/Articles/commercialqualityprogramming.pdf Dave Cole REPLY TO: [email protected] ColeSoft Marketing WEB PAGE: http://www.colesoft.com 736 Fox Hollow Road VOICE: 540-456-8536 Afton, VA 22920 FAX: 540-456-6658
