Wednesday, July 27, 2005
Seven, plus or minus two.
One of my best friends in high school, a woman who went on and became a doctor, told me of a test given to patients to help assess their cognitive functioning. You give them a list of numbers, and have them recite them back. Most people, when told a list of numbers and asked to recite them back again remember around seven numbers, give or take a few.
I had forgotten this cognitive test of short-term memory function until I was talking to a co-worker who was talking about the principle of coding, where objects, methods, collections of interfaces or whatnot should be developed in groups of seven, plus or minus two.
The idea is simple. The human brain can really only remember and hold seven things, give or take about two things, in short term memory without significant stress. So, for example, seven numbers--which is why American telephone numbers have seven digits in them--or seven objects, or seven names, or seven modules... Seven, give or take two.
Violate this principle and you just cause short-term confusion.
In the realm of programming, this principle is very important. In our quest to simplify a problem, we should be willing to break things down into managable chunks. And by "managable", I mean chunks that are roughly around seven "things", give or take two. Now this isn't a hard and fast rule--like all good rules, it must on occassion be violated. And by "things" I don't even necessarly mean seven methods per class or seven class per package. But the methods within a larger class should conseptually be "clumped": thus, while the java.awt.Graphics class has dozens of methods, conceptually they can be clumped into five rectangle methods, five circle methods, etc.
And while a package may have more than seven classes in it, conceptually those classes should also be "related": thus, six interfaces, eight exceptions, etc. You can even have more than nine implementation classes, so long as they are conceptually related, such as five classes that do one thing, four that do another. (Of course if what they do are sufficiently unrelated, perhaps they belong in a sub-package.)
Functionality for a larger program can also be broken down into clumps as well. From the Macintosh Toolbox, we had the Windows toolbox, the Dialog toolbox, the Control toolbox and the QuickDraw toolbox--four things which, in the larger scope of the Macintosh API, were conceptually related under the heading "GUI managers." (Separate were the File/Resources managers, the Network/Serial IO managers, etc.) Then under each toolbox, you had "stuff that creates instances", "stuff that manipulates instances", "stuff that destroys instances"--and so forth.
I believe this is a major shortcoming of the Javadocs program, by the way: it fails to allow programmers to clump related methods together and create a sort of "meta-index" of methods.
The way each Macintosh Toolbox chapter was very illustrative: it would give a one or two page introduction outlining what the toolbox did. Then it would give five or six sections illustrating what you could do and how to do it, in general terms. ("How a window interacts." "Window lifecycle." "How to manipulate windows." "How to handle window events.") Then at the end was the API specification--but broken down into clumps of functionality: the methods for opening a window, then the methods for manipulating window properties, then methods for window events, etc.
Javadoc, however, doesn't provide the ability to create "meta-clumping" of functions. While obviously Javadoc should never replace proper documentation, at the very least it should be possible to have a comment that essentially says "the next eight methods are all related to 'Thing'", which then generates an index at the top of the Javadoc page that says "Thing methods" that is a link to the 'thing' methods.
So while a class with 50 methods may observe the "seven plus or minus two" rule with seven sets of seven methods (give or take), Javadoc has no way for a developer to quickly show what those groups are.
And that's a shame. ¶ 9:11 PM
I had forgotten this cognitive test of short-term memory function until I was talking to a co-worker who was talking about the principle of coding, where objects, methods, collections of interfaces or whatnot should be developed in groups of seven, plus or minus two.
The idea is simple. The human brain can really only remember and hold seven things, give or take about two things, in short term memory without significant stress. So, for example, seven numbers--which is why American telephone numbers have seven digits in them--or seven objects, or seven names, or seven modules... Seven, give or take two.
Violate this principle and you just cause short-term confusion.
In the realm of programming, this principle is very important. In our quest to simplify a problem, we should be willing to break things down into managable chunks. And by "managable", I mean chunks that are roughly around seven "things", give or take two. Now this isn't a hard and fast rule--like all good rules, it must on occassion be violated. And by "things" I don't even necessarly mean seven methods per class or seven class per package. But the methods within a larger class should conseptually be "clumped": thus, while the java.awt.Graphics class has dozens of methods, conceptually they can be clumped into five rectangle methods, five circle methods, etc.
And while a package may have more than seven classes in it, conceptually those classes should also be "related": thus, six interfaces, eight exceptions, etc. You can even have more than nine implementation classes, so long as they are conceptually related, such as five classes that do one thing, four that do another. (Of course if what they do are sufficiently unrelated, perhaps they belong in a sub-package.)
Functionality for a larger program can also be broken down into clumps as well. From the Macintosh Toolbox, we had the Windows toolbox, the Dialog toolbox, the Control toolbox and the QuickDraw toolbox--four things which, in the larger scope of the Macintosh API, were conceptually related under the heading "GUI managers." (Separate were the File/Resources managers, the Network/Serial IO managers, etc.) Then under each toolbox, you had "stuff that creates instances", "stuff that manipulates instances", "stuff that destroys instances"--and so forth.
I believe this is a major shortcoming of the Javadocs program, by the way: it fails to allow programmers to clump related methods together and create a sort of "meta-index" of methods.
The way each Macintosh Toolbox chapter was very illustrative: it would give a one or two page introduction outlining what the toolbox did. Then it would give five or six sections illustrating what you could do and how to do it, in general terms. ("How a window interacts." "Window lifecycle." "How to manipulate windows." "How to handle window events.") Then at the end was the API specification--but broken down into clumps of functionality: the methods for opening a window, then the methods for manipulating window properties, then methods for window events, etc.
Javadoc, however, doesn't provide the ability to create "meta-clumping" of functions. While obviously Javadoc should never replace proper documentation, at the very least it should be possible to have a comment that essentially says "the next eight methods are all related to 'Thing'", which then generates an index at the top of the Javadoc page that says "Thing methods" that is a link to the 'thing' methods.
So while a class with 50 methods may observe the "seven plus or minus two" rule with seven sets of seven methods (give or take), Javadoc has no way for a developer to quickly show what those groups are.
And that's a shame. ¶ 9:11 PM
