home *** CD-ROM | disk | FTP | other *** search
/ NetNews Usenet Archive 1992 #30 / NN_1992_30.iso / spool / comp / software / 5031 < prev    next >
Encoding:
Text File  |  1992-12-17  |  2.4 KB  |  69 lines
  1. Newsgroups: comp.software-eng
  2. Path: sparky!uunet!mole-end!mat
  3. From: mat@mole-end.matawan.nj.us
  4. Subject: Re: C code Layout
  5. Message-ID: <1992Dec16.152026.28190@mole-end.matawan.nj.us>
  6. Summary: Final causes ...
  7. Organization: :
  8. References: <1992Dec14.074411@eklektix.com> <1992Dec14.175533.8400@fcom.cc.utah.edu>
  9. Date: Wed, 16 Dec 1992 15:20:26 GMT
  10. Lines: 57
  11.  
  12. > >back to Bryant, who talks about the difference between useless comments,
  13. > >like:
  14. > >>   i = i + 1;   /* Increment i */
  15. > >(no argument here, of course)
  16.  
  17. > >....and useful, necessary explanations like:
  18.  
  19. > >>   /*
  20. > >>    *  We are now done with the code for widget i, and while
  21. > >>    *  the "for" loop will increment i again, we want to skip
  22. > >>    *  the next widget and so we increment i here as well.
  23. > >>    */
  24.  
  25. > >>   i = i + 1;
  26.  
  27. > >The *idea* of commenting this situation is good.  You don't want somebody
  28. > >looking at it, wondering whether the increment is supposed to be there or
  29. > >was left over from a different sequence, etc...it's a good situation for
  30. > >stopping to describe what's going on.  It's the realization that is bad.
  31. > >(To a C programmer, the first problem is that the code should be
  32. > >    i++;
  33.  
  34. Pardon me for flaming, but ...
  35.  
  36. You are all of you looking in the wrong direction.
  37.  
  38. Any programmer can tell that i++ or i += 1 or i = 1 + 1 will increment
  39. the value.  And, with a little context, it should be clear that it means
  40. that the next widget will get skipped.  (If it is not clear, the code
  41. has other problems.)
  42.  
  43. But none of you, and none of this code, has addressed the ONE THING for
  44. which comments are necessary, the ONE THING which they can do that code
  45. can never do, no matter how good.
  46.  
  47. You haven't asked, much less answered, the ONE QUESTION that can assure
  48. us that this code is doing The Right Thing.
  49.  
  50. You haven't told us
  51.  
  52.     WHY WE SHOULD BE SKIPPING THE NEXT WIDGET.
  53.  
  54. What need is answered by skipping that widget?  To what end, for the
  55. satisfaction of what final cause, must that execrable, unspeakable,
  56. fetid, repellant, malodorous, pestilential, obscene, shameful, squalid,
  57. fulsome, abominable, noxious, rank, infamous next widget be skipped?
  58.  
  59. Tell me that, and then let me read your code to see what you've done
  60. about it.
  61.  
  62. ``Say what you mean, mean what you say, do what you said you would do.''
  63.  
  64. -- 
  65.  (This man's opinions are his own.)
  66.  From mole-end                Mark Terribile
  67.  
  68.  mat@mole-end.matawan.nj.us, Somewhere in Matawan, NJ
  69.