home *** CD-ROM | disk | FTP | other *** search
/ NetNews Usenet Archive 1992 #30 / NN_1992_30.iso / spool / comp / software / 4992 < prev    next >
Encoding:
Text File  |  1992-12-15  |  1.8 KB  |  45 lines
  1. Newsgroups: comp.software-eng
  2. Path: sparky!uunet!cis.ohio-state.edu!pacific.mps.ohio-state.edu!linac!att!cbnewsm!lfd
  3. From: lfd@cbnewsm.cb.att.com (Lee Derbenwick)
  4. Subject: Re: C code Layout
  5. Organization: AT&T
  6. Date: Tue, 15 Dec 1992 23:24:22 GMT
  7. Message-ID: <1992Dec15.232422.8142@cbnewsm.cb.att.com>
  8. Summary: Yes, _especially_ comment what isn't there.
  9. References: <1992Dec12.122453.8582@seq.uncwil.edu> <KANZE.92Dec15181119@slsvdnt.us-es.sel.de>
  10. Lines: 33
  11.  
  12. In article <KANZE.92Dec15181119@slsvdnt.us-es.sel.de>,
  13. kanze@us-es.sel.de (James Kanze) writes:
  14. [ ... ]
  15. > Again, if you leave out a test for some specific condition because you
  16. > are convinced that that condition can never occur, some comment as to
  17. > *why* you are convinced is in order.
  18. > 
  19. > And any time you use something other than the obvious solution, then
  20. > some comment as to why it wasn't used is in order.  Note that in this
  21. > case, you're actually commenting the code that *wasn't* written.
  22.  
  23. These are _very_ important points.  They also illustrate the futility
  24. of any fixed comments:code ratio.  "What is the appropriate ratio of
  25. comments to code that isn't there?"
  26.  
  27. Yet these are the scariest ones:
  28.  
  29.     /* no test for overflow here; the msg format only has 19 chars */
  30.  
  31. And then somebody changes the message format.  With the comment, you'll
  32. probably find the error in a reasonable amount of time.  Indeed, having
  33. seen the comment while looking for something else, you are likely to
  34. remember that there's _something_ you've got to change if the message
  35. format ever changes, and you've got a decent chance of locating it before
  36. it becomes an error.
  37.  
  38. Without a comment like that, lots of luck...
  39.  
  40. (Of course, you may note that my example comment is a one-liner.  :-)
  41.  
  42.  -- Speaking strictly for myself,
  43.  --   Lee Derbenwick, AT&T Bell Laboratories, Holmdel, NJ
  44.  --   lfd@cbnewsm.ATT.COM  or  <wherever>!att!cbnewsm!lfd
  45.