home *** CD-ROM | disk | FTP | other *** search
/ NetNews Usenet Archive 1992 #30 / NN_1992_30.iso / spool / comp / software / 4973 < prev    next >
Encoding:
Text File  |  1992-12-15  |  2.6 KB  |  58 lines
  1. Newsgroups: comp.software-eng
  2. Path: sparky!uunet!psinntp!ficc!rogers
  3. From: rogers@ferranti.com (keith rogers)
  4. Subject: Re: C code Layout
  5. Message-ID: <id.5BUV.CUB@ferranti.com>
  6. Keywords: comments
  7. Sender: rogers@ferranti.com
  8. Organization: Ferranti International Controls Corporation
  9. Date: Mon, 14 Dec 1992 23:37:56 GMT
  10. Lines: 46
  11.  
  12. In <1992Dec13.152430.6370@mixcom.com> ttvvtt@mixcom.com (Donald Amby) writes:
  13. >
  14. > <...> (R.T. Herbst) writes:
  15. >
  16. > >While directing the eforts of 125 people in producing the
  17. > >A Data switching system for the Bell System- Good ol'
  18. > >Ma bell-- I asked for a sample of code. I founr the comments to
  19. > >be utter nonsense,. If one removed the code, the comments made no sense.
  20. >
  21. >   Excellent point!   The comments SHOULD make sense without the code.
  22. >   I personally write code by doing the comments first.  If I cannot
  23. >   describe in clear concise sentences what I am attempting to do,
  24. >   then I obviously do not understand the problem.
  25. >
  26. >   I then add the code as I get the details of the implementation
  27. >   worked out.
  28.  
  29. What you are describing (to me, anyway) is design notes.  I don't agree
  30. that comments must stand by themselves.  A design, prior to coding,
  31. should meet that criteria, but once the code is written, the comments
  32. and code, together, should be used to convey the information necessary
  33. for proper maintenance of the software.  Insisting that the comments,
  34. without the code, be comprehensible, insures that your comments will
  35. contain needless, redundant information.  Commentary should be used to
  36. help people through obscure coding, and to document non-standard or
  37. unusual coding, e.g., where the "obvious" coding method would be
  38. different, and was not chosen for a specific reason.  (This, so some
  39. future maintainer doesn't toss out all of your good work, after having
  40. scratched their head over it for many hours and finally deciding,
  41. incorrectly, that it would be quicker, better, and easier to simply
  42. rewrite the code in a manner already rejected, than to try and fathom
  43. what the original coder had in mind.)
  44. >
  45. > >It was better to let the code speak for itself. If fact the code
  46. > >was hidden in by the comments. Certainly we need well commented code.
  47. >
  48. >   Organizations that are serious about quality should address the
  49. >   comments as part of any code review.  Of course, if there are
  50. >   no code reviews you will never see the comments until you have
  51. >   to make changes to the code.
  52.  
  53. And you shouldn't be surprised to never see any comments, at all,
  54. ever, if you never have code reviews.
  55. --
  56. Keith Rogers (rogers@ferranti.com)
  57. (jus' me talkin', an' nobody else)
  58.