home *** CD-ROM | disk | FTP | other *** search
/ NetNews Usenet Archive 1992 #27 / NN_1992_27.iso / spool / comp / software / 4469 < prev    next >
Encoding:
Internet Message Format  |  1992-11-23  |  2.3 KB
  1. Path: sparky!uunet!cs.utexas.edu!uwm.edu!ogicse!das-news.harvard.edu!cantaloupe.srv.cs.cmu.edu!tgl
  2. From: tgl+@cs.cmu.edu (Tom Lane)
  3. Newsgroups: comp.software-eng
  4. Subject: Re: Comments:Code (what is the standard guideline?)
  5. Summary: quantity != quality
  6. Message-ID: <By6I01.1wF.2@cs.cmu.edu>
  7. Date: 23 Nov 92 17:02:23 GMT
  8. Article-I.D.: cs.By6I01.1wF.2
  9. References: <1992Nov23.152046.5614@brtph560.bnr.ca>
  10. Sender: news@cs.cmu.edu (Usenet News System)
  11. Organization: School of Computer Science, Carnegie Mellon
  12. Lines: 38
  13. Nntp-Posting-Host: g.gp.cs.cmu.edu
  14.  
  15. markham@brtph678.bnr.ca (Andrew Markham P205) writes:
  16. > Some friends wanted to settle a dispute on the comments-to-code
  17. > ratio that is generally suggested in software engineering circles.
  18. > Two of us believe a 60:40 comment-to-code breakdown, but the other 
  19. > thinks that is simply too many comments.
  20.  
  21. IMHO the mere ratio of code to comment characters is uninteresting,
  22. and any attempt to standardize a ratio is bureaucratic mindlessness.
  23. The only useful measure of the value of comments is how much information
  24. they convey that isn't obvious from the code, and this is UNRELATED to
  25. volume.
  26.  
  27. Let me give you two examples at opposite extremes.  A sorting routine
  28. might well be considered fully commented with the single line
  29.     /* See Knuth's Art of Computer Programming, vol 3, pp 114-117 */
  30. if it is a direct implementation of Knuth's exposition of Quicksort.
  31. There is very little you would want to know that you wouldn't find
  32. in Knuth's book.
  33.  
  34. On the other hand, I have seen FAR too much assembly code in the style of
  35.     ...
  36.     add    #1,d3        ; add 1 to i
  37.     ...
  38. where the comments are voluminous but convey hardly any new information.
  39. (To say nothing of the possibility that the comments are actually in error.)
  40.  
  41. I also believe that assembly coding usually requires a greater density of
  42. comments than do high-level languages; for instance, you often use comments
  43. to mark constructs like loops, if-then-else, and so on, which require no
  44. comments in HLLs.  This suggests that any comment-to-code ratio is
  45. language-specific.
  46.  
  47. In short, the interesting question is not the volume of comments, it's
  48. the quality of the comments.  I'm not aware of any simple way of measuring
  49. the quality; I would say that almost by definition, there is no mechanical
  50. way of measuring it.
  51.  
  52.             regards, tom lane
  53.