home *** CD-ROM | disk | FTP | other *** search
/ NetNews Usenet Archive 1992 #30 / NN_1992_30.iso / spool / comp / software / 4970 < prev    next >
Encoding:
Text File  |  1992-12-15  |  4.9 KB  |  99 lines
  1. Newsgroups: comp.software-eng
  2. Path: sparky!uunet!wupost!spool.mu.edu!umn.edu!csus.edu!netcom.com!mcgregor
  3. From: mcgregor@netcom.com (Scott Mcgregor)
  4. Subject: Re: C CODE LAyout
  5. Message-ID: <1992Dec15.074041.472@netcom.com>
  6. Organization: Netcom - Online Communication Services (408 241-9760 guest)
  7. References: <1992Dec14.084405@eklektix.com> <MARTINC.92Dec14120615@hatteras.cs.unc.edu> <Bz9yzH.M97@fiu.edu>
  8. Date: Tue, 15 Dec 1992 07:40:41 GMT
  9. Lines: 88
  10.  
  11. In article <Bz9yzH.M97@fiu.edu> feathers@serss0 (Michael Feathers) writes:
  12.  
  13. >I am a firm believer in minimal commenting of code.  I try to write every
  14. >method in a self-explanatory manner and I have a sure-fire way of discovering
  15. >whether the meaning of the code is explicit enough to not require commenting:
  16.  
  17. It seems to me that the whole reason for this debate has to do with
  18. some important cognitive tradeoffs that we face. The problem is that
  19. the brain can only handle so much information. In an informal way, we
  20. might interpret the cognitive literature as saying that humans have
  21. 7+/-2 registers (this isn't entirely accurate, as I am completely
  22. aware, but it is more correct than not for the current purposes and
  23. can be discussed in more correct terms in comp.cog-eng).  What is
  24. really incredible about human's registers is that they aren't fixed
  25. lengths. If you can "chunk" a lot of information together into a
  26. single structure then you can remember and manipulate more complex
  27. things.  (See my "Designing for Usability" article in X-Resource
  28. Journal volume 2 for more info on how to apply some of this cognitive
  29. theory to problems in programming).
  30.  
  31. This turns out to be crucially important for programming. About the
  32. biggest chunk that most people can manage is a screen or a page's
  33. worth (The visual channel is the most high bandwidth channel for
  34. information chunking--**IF**the choice of visual representation
  35. successfully chucks the information for the reader.  As Tufte points
  36. out, this is a big **IF**!   (See Tufte: "Envisioning Information" and
  37. "The Visual Display of Quantitative Information").
  38.  
  39. In fact, if you watch programmers at work you can see this.
  40. Performance, in terms of accuracy (i.e. few bugs) and time to modify, drop off
  41. rapidly as routine size exceeds a page or screen. 
  42.  
  43. So on the one hand, this argues for as dense coding as possible,
  44. keeping comments terse.  However, then you run smack dab into the
  45. other aspect, that if symbolic processing of page overloads the
  46. programmer to the point where they can't "chunk" it all, performance
  47. gets worse, because then chunks are likely to be at the level of
  48. statements or small groups of statements. (Tufte points out this with
  49. respect to graphs and charts too--adding more to the chart in artful
  50. way conveys more at a single glance, but if you overload it destroys
  51. the possibility of understanding anything). This is what makes
  52. conveying information (whether in a coded algorithm or graph) an art,
  53. and not a science.
  54.  
  55. One other thing that is relevant is that they ability to chuck things
  56. at a certain level is based upon past experience. So things that you
  57. have already seen and learned can become a short hand and more easily
  58. chunked. This means that the person who has seen the code a lot of
  59. times, or just someone who is more experienced in general, will be
  60. able to chuck more code (i.e. understand more at one time) than
  61. someone who is new to the code, or even just less familiar with those
  62. kinds of structures. Unfortunately, the authors of programs are more
  63. likely to be of the former class, and the maintenance programmers who
  64. follow are more likely to be the latter class, so the former sometimes
  65. has difficulty providing successfully for the needs of the latter.
  66.  
  67. A lengthy explanation in a comment can be a way to set up a "tree of
  68. ideas" upon which various concepts are hung one at a time to build up
  69. a very large chunk of understanding for someone who is new to much of
  70. it. But it occupies valuable space for the expert. Hence the conflict.
  71. The problem exists in every code representation.  But some
  72. representations (e.g. programming languages, APIs, library calls...)
  73. are better than others. And supporting system that allow quick cross
  74. reference between explanations and implementations, without using
  75. valuable space, can be constructed. (See my "Prescient Agents" article
  76. in X Resource Journal volume 0 for an example).
  77.  
  78. If more attention were paid directly to some of these cognitive
  79. issues, particularly in choosing better algorithm representation and
  80. support, I suspect that there would be more agreement on these
  81. debates, at least about the guiding principles, but probably also
  82. about particular case studies.
  83.  
  84.  
  85.  
  86. -- 
  87.  
  88. Scott L. McGregor        mcgregor@netcom.com
  89. President            tel: 408-985-1824
  90. Prescient Software, Inc.    fax: 408-985-1936
  91. 3494 Yuba Avenue
  92. San Jose, CA 95117-2967
  93.  
  94. Prescient Software sells Merge Ahead, the tool for Merging Text or Code and
  95. offers consulting  & training in project management and design for usability.
  96.  
  97.  
  98.  
  99.