home *** CD-ROM | disk | FTP | other *** search
/ NetNews Usenet Archive 1992 #30 / NN_1992_30.iso / spool / comp / software / 4887 < prev    next >
Encoding:
Internet Message Format  |  1992-12-11  |  2.2 KB
  1. Xref: sparky comp.software-eng:4887 comp.lang.c:18224
  2. Newsgroups: comp.software-eng,comp.lang.c
  3. Path: sparky!uunet!sarge!monster.apd.saic.com!tomj
  4. From: tomj@monster.apd.saic.com (Tom Johnson)
  5. Subject: Write Only Commentary (Was Re: C Code Layout)
  6. Message-ID: <Bz3zGA.DG4@monster.apd.saic.com>
  7. Organization: SAIC, Reston, VA
  8. References: <1992Dec7.113438.13054@spider.co.uk> <1992Dec7.164154.6312@b30.ingr.com> <BywqDo.F8F@monster.apd.saic.com> <1992Dec10.191917.18184@yarc.uucp>
  9. Distribution: comp
  10. Date: Fri, 11 Dec 1992 19:00:09 GMT
  11. Lines: 47
  12.  
  13. >>>>3. What formats are most effective for comment headers of
  14. >>>>functions and what kind of information is appropriate for these.
  15. >>>
  16. >
  17. >>HISTORY
  18. >>       Author     Date          Description
  19. >>       -----      ----          -----------
  20. >>        pam     12/07/91        initial spec
  21. >>        moh     12/18/91        made arg1 optional
  22. >>        xac     06/22/92        correct something TR 92w1234
  23. >
  24. >I've always wondered about this sort of thing in a source file.
  25. >Is this sort of information considered useful?  I know several 
  26. >programmers who refer to this as "write-only" documentation ....
  27. >stuff that's written down, never to be looked at again :-)
  28. >
  29. >Is there a general consensus that these sorts of comments are
  30. >Good Things, or a waste of time?  I, personally, care more
  31. >about what the function _is_, rather than what it _was_.
  32. >
  33. >Inquiring minds want to know.
  34. >
  35. >--tom
  36. >
  37.  
  38. There's been lots of discussion about this topic, via E-mail and in
  39. comp.lang.c, so I thought I'd post a summary of the responses.
  40.  
  41. Most people agree that this sort of information is useful (and I never
  42. intended to imply that it wasn't; just its usefulness in the source file.
  43. That'll teach me to type so fast!)
  44.  
  45. The opinions were pretty evenly split amongst programmers who think that
  46. the information should be actually in the source code, and those who think
  47. it belongs elsewhere.  "Elsewhere" usually means some sort of automated
  48. trouble report tracking system.
  49.  
  50. By far the most common argument for its usefulness was that automated tools
  51. do it automatically.  Can't beat THAT logic!
  52.  
  53. To anyone who E-mailed me and got no response, sorry.  There were more
  54. than a I could get to!
  55.  
  56. C you,
  57. -- tom
  58.  
  59.  
  60.