home *** CD-ROM | disk | FTP | other *** search
/ NetNews Usenet Archive 1992 #30 / NN_1992_30.iso / spool / comp / software / 4912 < prev    next >
Encoding:
Text File  |  1992-12-13  |  1.9 KB  |  52 lines
  1. Newsgroups: comp.software-eng
  2. Path: sparky!uunet!psinntp!wrldlnk!usenet
  3. From: "Lih Yen Hsieh" <wk01673@worldlink.com>
  4. Subject: Re: C Code Layout
  5. Message-ID: <2933199653.8.wk01673@worldlink.com>
  6. Sender: usenet@worldlink.com
  7. Nntp-Posting-Host: 127.0.0.1
  8. Organization: [ Myself ]
  9. Date: Fri, 11 Dec 1992 22:44:33 GMT
  10. X-Mailer: WORLDLink (3.11)
  11. Lines: 39
  12.  
  13. Tom Johnson <tomj@monster.apd.saic.com> writes:
  14. >
  15. >mueller@b30news.b30.ingr.com ( Phil Mueller ) writes:
  16. [ ommisions ]
  17. >
  18. >>HISTORY
  19. >>       Author     Date          Description
  20. >>       -----      ----          -----------
  21. [ omissions ]
  22. >I've always wondered about this sort of thing in a source file.
  23. >Is this sort of information considered useful?  I know several 
  24. >programmers who refer to this as "write-only" documentation ....
  25. >stuff that's written down, never to be looked at again :-)
  26. >
  27. >Is there a general consensus that these sorts of comments are
  28. >Good Things, or a waste of time?  I, personally, care more
  29. >about what the function _is_, rather than what it _was_.
  30.  
  31. I will be amazed if "software engineers" were cited in the counter point.
  32. Inclusion of historical information about the module certainly helps track
  33. the evolution of the piece of code of interest.  Points of relevance:
  34.  
  35. 1. When you need to deal with FDA audits.
  36. 2. When you have to inherit code from previous contributors.
  37. 3. WHen you work on a project that contains at least dozens of source files.
  38. 4. When you are working on complex modules.
  39. etc.
  40.  
  41. Practically, if you are in a production environment, this is not only
  42. a good thing to have, but also indispensible and should be enforced.
  43. (I was able to get by without documenting code history when I was
  44. programing for my master's thesis work. But now at work I enforce it.)
  45.  
  46. If you are familiar with Unix tools, such as sed, awk, and the like, you
  47. can craft non-trivial tools together with revision control and the make
  48. program to somewhat mechanize this 'chore'.
  49.  
  50. Lih-Yen Hsieh
  51.  
  52.