home *** CD-ROM | disk | FTP | other *** search
/ NetNews Usenet Archive 1992 #30 / NN_1992_30.iso / spool / comp / software / 4953 < prev    next >
Encoding:
Text File  |  1992-12-14  |  3.0 KB  |  58 lines
  1. Newsgroups: comp.software-eng
  2. Path: sparky!uunet!elroy.jpl.nasa.gov!swrinde!zaphod.mps.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: Mon, 14 Dec 1992 23:55:21 GMT
  7. Message-ID: <1992Dec14.235521.1557@cbnewsm.cb.att.com>
  8. Summary: BSD utilities != UNIX source code, plus large-comment maintenance.
  9. References: <1992Dec14.074411@eklektix.com> <1992Dec14.175533.8400@fcom.cc.utah.edu>
  10. Lines: 46
  11.  
  12. In article <1992Dec14.175533.8400@fcom.cc.utah.edu>, bryant@ced.utah.edu (Bryant Eastham,MEB 3116,581-5353) writes:
  13. > In article 074411@eklektix.com, rcd@raven.eklektix.com (Dick Dunn) writes:
  14. > >Next, step back and look at where UNIX has gone.  That code has been read
  15. > >and understood by tens of thousands of people, and has been successfully
  16. > >modified over and over again for many years, often by people with almost no
  17. > >training or aptitude.  Like it or not, there is massive evidence that the
  18. > >style DOES work, IS understandable, and IS maintainable.  It's *not* the
  19. > >only workable style!  But it works.
  20. > 
  21. > I suppose that explains why the examples of poor (very poor) commenting
  22. > style for my senior lab class were from the source for UNIX! No lie,
  23. > one assignment was to comment the command "strings", which (from the
  24. > distribution) had (if I remember right) ONE COMMENT LINE. I don't know
  25. > who that style works for. Certainly not anyone in the class or the
  26. > instructors.
  27.  
  28. This is a poor counterexample, because the "strings" command was
  29. added by someone at UC Berkeley; it's unfair to count it as part of
  30. the UNIX source code cited by Dick Dunn.  Certainly not in a thread
  31. that had mentioned Kernighan and Ritchie.  From your description of
  32. the source code, it doesn't sound as if strings.c was commented in
  33. anything resembling "K&R style".
  34.  
  35. One reason that I personally dislike very large comments embedded in
  36. the code is that they greatly reduce the amount of code within my
  37. visual field (whether on a screen or on paper): they increase the
  38. number of fingers I need to read the code.  [An interesting
  39. "difficulty" metric that I've seen attributed to Tom DeMarco.]
  40.  
  41. Another reason, potentially more damaging in the long run, is that
  42. long comments don't seem to be maintained as well as short ones.
  43. Somebody changed the code, but didn't go back to update the fourth
  44. line of the fifteen-line comment back at the beginning of the loop.
  45. So the comment now lies about what the code is doing.  That seems
  46. to happen far less often with concise comments attached to the code
  47. they describe.
  48.  
  49. This second problem may also occur with literate programming
  50. systems. They are still too new to have had large, production code
  51. maintained for several years in them.  It will be interesting to
  52. see if they avoid the problem of the text being less-maintained
  53. than the executable code itself.
  54.  
  55.  -- Speaking strictly for myself,
  56.  --   Lee Derbenwick, AT&T Bell Laboratories, Holmdel, NJ
  57.  --   lfd@cbnewsm.ATT.COM  or  <wherever>!att!cbnewsm!lfd
  58.