From: mcgregor@netcom.com (Scott Mcgregor)
Subject: Re: C CODE LAyout
Organization: Netcom - Online Communication Services (408 241-9760 guest)
Date: Tue, 15 Dec 1992 07:40:41 GMT

In article <Bz9yzH.M97@fiu.edu> feathers@serss0 (Michael Feathers) writes:

>I am a firm believer in minimal commenting of code.  I try to write every
>method in a self-explanatory manner and I have a sure-fire way of discovering
>whether the meaning of the code is explicit enough to not require commenting:

It seems to me that the whole reason for this debate has to do with
some important cognitive tradeoffs that we face. The problem is that
the brain can only handle so much information. In an informal way, we
might interpret the cognitive literature as saying that humans have
7+/-2 registers (this isn't entirely accurate, as I am completely
aware, but it is more correct than not for the current purposes and
can be discussed in more correct terms in comp.cog-eng).  What is
really incredible about human's registers is that they aren't fixed
lengths. If you can "chunk" a lot of information together into a
single structure then you can remember and manipulate more complex
things.  (See my "Designing for Usability" article in X-Resource
Journal volume 2 for more info on how to apply some of this cognitive
theory to problems in programming).

This turns out to be crucially important for programming. About the
biggest chunk that most people can manage is a screen or a page's
worth (The visual channel is the most high bandwidth channel for
information chunking--**IF**the choice of visual representation
successfully chucks the information for the reader.  As Tufte points
out, this is a big **IF**!   (See Tufte: "Envisioning Information" and
"The Visual Display of Quantitative Information").

In fact, if you watch programmers at work you can see this.
Performance, in terms of accuracy (i.e. few bugs) and time to modify, drop off
rapidly as routine size exceeds a page or screen. 

So on the one hand, this argues for as dense coding as possible,
keeping comments terse.  However, then you run smack dab into the
other aspect, that if symbolic processing of page overloads the
programmer to the point where they can't "chunk" it all, performance
gets worse, because then chunks are likely to be at the level of
statements or small groups of statements. (Tufte points out this with
respect to graphs and charts too--adding more to the chart in artful
way conveys more at a single glance, but if you overload it destroys
the possibility of understanding anything). This is what makes
conveying information (whether in a coded algorithm or graph) an art,
and not a science.

One other thing that is relevant is that they ability to chuck things
at a certain level is based upon past experience. So things that you
have already seen and learned can become a short hand and more easily
chunked. This means that the person who has seen the code a lot of
times, or just someone who is more experienced in general, will be
able to chuck more code (i.e. understand more at one time) than
someone who is new to the code, or even just less familiar with those
kinds of structures. Unfortunately, the authors of programs are more
likely to be of the former class, and the maintenance programmers who
follow are more likely to be the latter class, so the former sometimes
has difficulty providing successfully for the needs of the latter.

A lengthy explanation in a comment can be a way to set up a "tree of
ideas" upon which various concepts are hung one at a time to build up
a very large chunk of understanding for someone who is new to much of
it. But it occupies valuable space for the expert. Hence the conflict.
The problem exists in every code representation.  But some
representations (e.g. programming languages, APIs, library calls...)
are better than others. And supporting system that allow quick cross
reference between explanations and implementations, without using
valuable space, can be constructed. (See my "Prescient Agents" article
in X Resource Journal volume 0 for an example).

If more attention were paid directly to some of these cognitive
issues, particularly in choosing better algorithm representation and
support, I suspect that there would be more agreement on these
debates, at least about the guiding principles, but probably also
about particular case studies.



-- 

Scott L. McGregor		mcgregor@netcom.com
President			tel: 408-985-1824
Prescient Software, Inc.	fax: 408-985-1936
3494 Yuba Avenue
San Jose, CA 95117-2967

Prescient Software sells Merge Ahead, the tool for Merging Text or Code and
offers consulting  & training in project management and design for usability.



Newsgroups: comp.software-eng