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
