Subject: RE: PPIG discuss: statistical study about commenting >I think comments within code are often a waste of time, at least >in high level languages.
That certainly *can* be true. Consider the tautological example: ��// this comment is useless :-) My all-time favorite example, however, came from an assembly language function in the old Honeywell B library, which stated: �; if you think you know what those last two instructions did, �; you're just fooling yourself. This has the charming property of showing both that comments can be useless and can be essential (by gum, I *couldn't* figure out what those last two instructions were for -- I sure wish there had been a comment to tell me!). >�The code expresses the ideas logically >and unambiguously, which is much harder to do in a natural >language. That certainly *can* be true. However, if you've ever graded beginning programming classes, you surely have seen that it is easy to construct code that is unambiguously illogical. From some perspective, code is always unambiguous, in that it presumably has a precise meaning to the language compiler (language lawyers know this to be an idealization). However, it's certainly not hard to write code that is ambiguous in the sense that the reader will be almost certainly unable to intuit the author's true intent (Why is that buffer 1 bigger than it needs to be? Did he miscount, or does he know something I don't??? �Why did he make that a global variable when no other functions seem to be accessing it? Why did he make that maximum array size 31 instead of a nice round number? Was it something to do prime numbers? Or did it need to be one less than a power of 2 for some reason? etc.) >�The code expresses the ideas logically >and unambiguously, which is much harder to do in a natural >language. But the *real* problem with this statement is that code does *not* express ideas. It expresses very, very detailed (and often uninteresting) implementation decisions. If code were the ideal language for expressing ideas, then you would never see diagrams on the whiteboards of programmers -- you would only see reams of detailed code (in fact, it's likely there would be no whiteboards, since the computer terminal is a much better place to type code). One must reverse engineer ideas from code, and without documentation that often is extremely tedious and time-consuming, and sometimes impossible. Programmers are constantly talking about ideas (abstract, high-level things) with each other, and they almost never use code to carry on that conversation! >�If the functions and variables are given sensible >�names, their meaning is usually clear enough. But this statement seems to ignore the fact that there is little agreement about what is "sensible". For example, Simonyi, regarded as a great programmer by many, passionately argued against variable names containing *any* mnemonic information (in his original manifesto for the "Hungarian" naming convention, not the more politically correct later revisions). Many people believe this is sensible; many people believe it is nonsense. Midway between those two extremes is (for example) the old Bell Labs crowd, who believes that variables like "i" are fine, and long names are to be avoided. I know many people that, like myself, find it difficult to read other people's code, despite the fact that those authors insist they wrote logical, unambiguous code, with sensible function and variable names. Thus, this standard of coding has proven experientially useless for me. >�(Writing comments >or documentation outside of a program could be useful, however, >for example in giving instructions about how to use a class.) Certainly can be true, although I know of people who refuse to look at such documentation and insist on seeing the source code instead. Some of them claim such documentation is useless, because it could be wrong. >Whenever I've had to understand someone else's code, the first >thing I do is delete all the comments because they are usually >just clutter. Ah, then clearly your environment has provided conditioning that would tend to make you respond negatively to comments. Because much of my initial learning took place in an environment where documentation of various forms (including comments) was valued, and generally useful, my environment has conditioned me in the opposite direction. We're all just starving pigeons in the Skinner Box of Life :-). >Where I work now no one writes comments, probably because >the managers are programmers so they know it's a waste of >time. It certainly can be a waste of time (and why shouldn't it be -- does anyone teach programmers how to write documentation, let alone comments?), but there are also programming cultures quite different than the one you're in currently, where comments are used and not at all a waste of time. I wouldn't attempt to sell the value of documentation (including comments) to your workgroup any more than I would try to sell the value of software methodology to Microsoft. Programming cultures are powerful and diverse, and rarely admit change. The great thing about code is that there are innumerable ways to arrive at it. The bad thing about code is that there are innumerable ways to arrive at it :-). - Automatic footer for [EMAIL PROTECTED] ---------------------------------- To unsubscribe from this list, mail [EMAIL PROTECTED] unsubscribe discuss To join the announcements list, mail [EMAIL PROTECTED] subscribe announce To receive a help file, mail [EMAIL PROTECTED] help This list is archived at http://www.mail-archive.com/discuss%40ppig.org/ If you have any problems or questions, please mail [EMAIL PROTECTED]
