home *** CD-ROM | disk | FTP | other *** search
/ NetNews Usenet Archive 1992 #30 / NN_1992_30.iso / spool / comp / software / 4904 < prev    next >
Encoding:
Text File  |  1992-12-12  |  2.4 KB  |  61 lines
  1. Newsgroups: comp.software-eng
  2. Path: sparky!uunet!zaphod.mps.ohio-state.edu!caen!hellgate.utah.edu!fcom.cc.utah.edu!mars.ced.utah.edu!bryant
  3. From: bryant@ced.utah.edu (Bryant Eastham,MEB 3116,581-5353)
  4. Subject: Re: C code Layout
  5. Message-ID: <1992Dec12.200619.29602@fcom.cc.utah.edu>
  6. Sender: news@fcom.cc.utah.edu
  7. Reply-To: bryant@ced.utah.edu
  8. Organization: Center for Engineering Design
  9. References: <1992Dec12.122453.8582@seq.uncwil.edu>
  10. Date: Sat, 12 Dec 92 20:06:19 GMT
  11. Lines: 48
  12.  
  13. In article 8582@seq.uncwil.edu, herbst@seq.uncwil.edu (R.T. Herbst) writes:
  14. >While directing the eforts of 125 people in producing the 
  15. >A Data switching system for the Bell System- Good ol'
  16. >Ma bell-- I asked for a sample of code. I founr the comments to
  17. >be utter nonsense,. If one removed the code, the comments made no sense.
  18. >It was better to let the code speak for itself. If fact the code
  19. >was hidden in by the comments. Certainly we need well commented code.
  20. >Too many comments that try to say what the code is saying are IMHO
  21. >distracting. The code in this case was assembler. Since that time
  22. >higher level languages came into use. In particular C language.
  23. >My philosophy is to let the language speak for itself. Add comments
  24. >where necessary. Again while directing the efforts of hundreds of
  25. >people on the Safequard Anti-Balistic Missile System, we set standards
  26. >for commenting that let the code be seen. The project met its objectives
  27. >and schedule -- one of the few in that time frame. 
  28. >Flame on and damned be he or she who flames out.
  29. >herbst@seq.uncwil.edu
  30.  
  31. Anyone can get lucky a couple of times. ;-)
  32.  
  33. If you believe that K&R is "about right", then we will never
  34. come to agreement on what the right amount of comments is.
  35.  
  36. There is a difference between "letting the code speak for itself" and
  37. trying to let the code explain the algorithm. Clearly, lines like:
  38.  
  39.    i = i + 1;   /* Increment i */
  40.  
  41. are useless and cause "clutter" that should be "avoided". But the
  42. same line:
  43.  
  44.    /*
  45.     *  We are now done with the code for widget i, and while
  46.     *  the "for" loop will increment i again, we want to skip
  47.     *  the next widget and so we increment i here as well.
  48.     */
  49.  
  50.    i = i + 1;
  51.  
  52. can be a lifesaver for some poor person trying to maintain the
  53. code at a later time. The fact is that the second comment is
  54. MUCH larger and could even "hide the code", but there is no
  55. way that I will stop putting such comments in my code. I care
  56. too much for those who will follow me.
  57.  
  58. Bryant Eastham
  59.  
  60.  
  61.