Documentation

Andy,

Here's a first sample -- I figure we'll either agree or agree to disagree
before putting too much effort in.  I wrote this to replace the class
comment for Array.  It could also be used in "About" methods, help,
tutorials, and so on.  IMHO it's way more helpful than the existing class
comment.  Further improvements welcome.

'Array is the simplest data structure beyond a single variable.
 Imagine a row of numbered jars.
 You can put any object in any jar using at: aJarNumber put: anObject.
 You can view the contents using at: aJarNumber which must be an integer.

Arrays have the limitation of being fixed length.
 You can define virtually any length with Array new: size.

More complex data structures use Arrays to hold their variables and grow by
copying to a bigger Array or organizing groups of Arrays.

Arrays can be used in loops.
 array do: [:jar | "action on individual jar contents").

For more information on Arrays be sure to see the Help reference and
tutorial information.'

Kirk

Suggestion for class "about" methods.

I've noticed some goodies have about methods which contain the standard
copyright notice and that's all, absolutely no help whatever.  I started
using about methods during Digitlalk days when there were no such thing as
class comments as a place to save some class purpose and post-construction
analysis information.  Here's a small example:

about
"Page methods
copyright (c) 2000, Expertek
all rights reserved"

"Page is a quantized unit of disk space in a linked list
to hold node or blob objects of varying size. When a
page is called into cache by a BTree, it assembles the
whole object from the list and when written it chops
an object into a list of pages.

Page holds these objects:
content - one node with keys & data or blob object
nextPage - pointer to next page of content or nil (on disk only)
position - pointer to disk position (not saved)
"

This documentation could of course be placed in class comments now.  But it
has a certian attractiveness not included in my previous Array class comment
in detailing how specific instance variables are used and how the class
interrelates to other classes in the intended application.  It does not have
simple usage help though.

These examples can be discussed and perhaps we can derive a moderate
standard for what constitutes "useful" class documentation as opposed to the
other kind.

Regards,
Kirk

Here is a brief discussion of documentation theory including why Patterns
suck and should not be pursued.  Also, I'm taking the liberty of bringing
forward Bill's salient remark on why we need documentation, which is:

"And the cost of not doing it?  IMHO, the new code that I'm seeing is going
to put the cost on the back end.   And I'm not sure I'm comfortable with the
analogy to strong typing.  That's perhaps in part because I don't expect
comments to be error-free; sometimes it's helpful to know what the developer
thought at some point in time (for formulating theories about what might be
wrong) or something close but not quite right might make the updated code
easier to understand."  - Bill Schwab.

So far we have these types of documentation content proposed:
1) A practical statement about why the class exists.
2) How to immediately use the class stand-alone in interesting ways.
3) How the class is used in combination with other classes.
4) Developer's thoughts (for ideas on what might be wrong).
5) Owner Copyright information - (assumed for packages?).
6) Instance variable content documentation.
7) Usage assumptions - what must be true to make it work.
8) Notice that the class is an Ansi Smalltalk Standard Class or not.

Any further ideas as to what constitutes useful documentation that is brief
and easy to maintain?  Should we extend the list or can we prune the list
without losing helpfulness value?

-------------Patterns Exposed-----------------

Notice these class documentation values do not (and hopefully will not)
include "Patterns."  That is because patterns are not specific algorithms
nor helpful documentation.  Patterns are just unnecessary style suggestions
which are better left to an integrated methodology like Extreme Programming
or a company style manual.

One of Smalltalk's interesting research and development issues was the
creation of the object paradigm which necessitated the paradigm shift in all
other viable programming languages.  But the essence of a paradigm is a new
perspective or viewpoint consisting of redefined words that essentially mean
the same thing.  Value was present because objects do make it easier to
program.  Like the object paradigm shift, the shift to Extreme Programming
started with Smalltalk and is percolating through other languages because it
makes programming easier.

Many people were fooled by the snake-oil of the patterns paradigm because
"patterns" sounds important like "objects" and the books of patterns were
far easier to write than tested algorithms so quite a few were written.  But
unlike patterns for cutting out clothing, these software patterns did not
make it easier to write programs.  That is why patterns have gone away
except for a few diehards who still believe the pattern paradigm hype.

-----------------------------------------------------

Further discussion on documentation that would actually help make
programming easier is encouraged!!!

Kirk Fraser

Kirk W. Fraser <[hidden email]> wrote in message
news:bAnB9.26960$A%[hidden email]...
> Andy,
>
> Here's a first sample -- I figure we'll either agree or agree to disagree
> before putting too much effort in.  I wrote this to replace the class
> comment for Array.  It could also be used in "About" methods, help,
...

This sounds good except I am not sure about the reference to "numbered
jars".  Your comment would be great for someone totally new to programming
(and maybe that is a good idea after all), but I am not sure if it is a
little too detailed for a class comment in the image.  I don't think the
"For more information..." bit at the end is necessary, unless it referred to
a specific source.  If it included code to open the manual on Array
documentation it might have value.  Also the comment should explain that
Array indexes are 1 based.

Chris

Kirk W. Fraser <[hidden email]> wrote in message
news:eEuB9.26967$A%[hidden email]...
>
> So far we have these types of documentation content proposed:
...
> 4) Developer's thoughts (for ideas on what might be wrong).

I am not sure if this needs to be a specific item.  If all other points are
documented then we may be able to infer what the developer was thinking.
Perhaps this could be an optional item, added only if it adds value to the
comment.


> -------------Patterns Exposed-----------------
>
> Notice these class documentation values do not (and hopefully will not)
> include "Patterns."  That is because patterns are not specific algorithms
> nor helpful documentation.  Patterns are just unnecessary style
suggestions
> which are better left to an integrated methodology like Extreme
Programming
> or a company style manual.
...

Gee, what did patterns ever do to you? ;)  I am certainly not a Patterns
expert, but I do find some value in them.  I don't believe that everything
needs to be distilled into a pattern.  However I think I have benefited from
reading about some patterns, and I think they are a useful communication
aid.

Are you saying that it would be bad to make reference to a class being a
Singleton or using a Wrapper pattern in the class comment?  I think these
are useful descriptions as they help me understand how the class works on an
overview basis without having to study the implementation or documentation
closer.  I am not implying that a pattern reference should be used instead
of documentation, but I don't think it hurts the documentation to have it
either.

I think in moderation patterns are useful.  Perhaps they may have been
abused by some.  So has cough syrup, but that doesn't make it inherently
evil.

Chris

Kirk W. Fraser wrote:

> Here's a first sample [snipped]

Hmm, I'm not at all sure that I like this.  (Personal opinion of course)

I think you/we need to distinguish between two rather vague concepts: between
"tutorial" information and "developer" information.  I don't claim there's a
really clean distinction between them, but it's more of an axis along which any
given bit of documentation can be placed.

I'd say that the image is no place for tutorial comments -- the writer of class
comments can *and should* assume that the reader understands Smalltalk basics.
So while I think text like yours has a useful place in the overall
documentation, I don't think the Array class comment is the place for it.

Actually I think you've chosen a rather unfortunate example -- Array, perhaps
uniquely in the whole image, doesn't seem to require a class comment at all.

However, for expository purposes, lets pretend that it, and the way it behaves,
are not part of the Smalltalk underpinnings, but that it's a new optimised
Collection class that Blair has just introduced in the latest release of
Dolphin.  What would the comment need to say then ?

Well for a start it wouldn't need to say that it held integer-indexed slots,
accessed by (1-based) #at: and #at:put:.  These qualities are intrinsic to
SequenceableCollection.  Nor, by similar reasoning, would it be appropriate to
mention #do:, etc.

What the comment should say is how Array differs from its superclass (what new
features it offers), what restrictions it imposes, how it relates to similar
classes, and anything "odd" about it (i.e ways in which it doesn't behave like
a typical Collection.  (I'm not claiming that that list is sufficient or ideal
for *all* class comments, more of that later.)

So, I think an appropriate comment (if one were needed) should read something
like:

----------------------
Array is a <SequencableCollection> optimised for very fast lookup via #at: and
#at:put:, but at the cost of automatic resizing.

Unlike most other Collections the size of an Array is not determined by how
many items have been added, but instead is fixed when the Array is created, and
can only be changed thereafter by the #resize: message.  The slots of an array
initially all hold nil.  Because the size does not vary automatically Arrays do
not implement the Collection>>add: method.

Note that not all Smalltalk implementations allow Arrays to be resized using
#resize:, so code that is intended to be portable should avoid using it.

Arrays can be created by the compiler as literal expressions like #(1 2 3 4) or
#('this' 'is' 'an' 'Array'), a particularly useful example is the empty Array,
written #().  You should treat all array literals as immutable.

See OrderedCollection for a Collection that is similar to an Array but which is
automatically resized as items are added and removed.
----------------------

(The wording could be improved, but I think the content is about right.)

A similar comment for OrderedCollection, that provides parallel information and
also refers to Array, is left as an exercise for the reader ;-)

For classes which are not embedded in a well-known framework, it would be
appropriate to provide more information.  The thing to consider is the need of
the reader.  Some classes are so obscure that a 1-liner is sufficient.  Others
form difficult-to-understand elements of complex frameworks, and long comments
giving examples of use, references to other classes, etc, are almost mandatory
(e.g. the Command classes -- which b.t.w do have decent comments, although
still rather hard to follow).  Most classes fall somewhere between these two
extremes, and have intermediate requirements for "ideal" comments.

I don't particularly like the "checklist" approach to comments of any sort
(Kirk didn't advocate any such thing, I know, I'm just rambling on).  It tends
to lead to lazy comments that minimally fulfil the requirements defined by the
list, but which provide no useful information at all.  Repeating myself: the
programmer writing the comment has to consider the needs of the reader.  Basing
the decision on what to document on what some "standard" requires, what is
less-than-obvious to the programmer him or herself, or on what is not obvious
from the code will all lead to bad commenting.

I want to expand a little on that last point.  It is frequently claimed that
documenting what is obvious is a waste of time.  I don't agree fully, for two
reasons.  One is that I've never seen it put forward in real life (i.e. where I
knew the programmer and had seen his code, and well as hearing the opinion
expressed) where it wasn't just a cover-up for laziness.  A touchstone for
whether the programmer is being "lazy" when applying the
if-its-redundant-then-leave-it-out rule, is what they do in the cases of doubt.
My own experience is that programmers who claim that their code doesn't need
(many) comments *invariably* write code that does need (more) comments -- it
just doesn't have (enough of) them.

The second reason is perhaps more interesting.  I dispute the unspoken
assumption that redundancy is bad.  Redundancy in *code* is certainly bad,
"once and once only" is an excellent guideline.  But redundancy in
*communication* is desirable and often necessary.  Explaining something in two
ways is better than explaining it in one.  Stating something twice (in two way)
is more reliable than stating it once.

That's my last substantive comment in this post.  I'm going to finish with a
little story, but if you think I've waffled on more than enough already, then
you can skip it without loss...

    -- chris

=============

How I Once Nearly Destroyed the Firm I Worked For.

Some years ago I was working for a small company that had just landed a really
important contact.  The contract was the biggest the company had ever had, and
was for software for a big new spin-off operation set up by a potentially
valuable new customer.  My employers had tendered at a very low price (I think
less than break-even) because getting the contract would open up a lucrative
new market -- not just the new customer but a whole market sector.  A
deliberate gamble.

Naturally, the tender was based on the initial estimate of what was required,
and naturally that estimate was too low.  By a factor of about 4.  Since even
the initial estimate called for using most of my employer's resources for about
a year, this meant that they were in serious bother.

I had very little to do with all that, I was just a programmer (working in C,
which gives you some idea how long ago this was :-)  I had quite a responsible
job, though -- I was writing stuff that was central to the viability of the
operation itself.  It *had* to work.

It didn't.

The customer had been well pissed-off anyway.  We were running unacceptably far
behind schedule (remember the initial estimates were way off).  We had been
forced to employ a large number of (very expensive) contractors to try and get
things done in something like the available time, and what with that and the
pressure, the bug-counts were way too high.  But then, on top of all that, the
key function was failing intermittently, and -- after some months -- still
nobody had a clue what was causing it.

I don't say it was *very* likely, but it was certainly on the cards that the
customer could just cancel the contract, and either cancel or postpone the new
spin-off operation.  If that had happened then my employer would have gone
under.

One day, one of the other programmers was reading though my database
initialisation code and he noticed something roughly like:

    /*
     * set the isolation level to read-repeatability; that's the default
     * anyway, but just to be sure
     */
    if (abc_set_is_lvl(db, ABC_ISL_RP) != ABC_OK)
        ...

A completely redundant comment (unless you consider that the horrible
identifiers chosen by the third-party database vendor made them necessary -- I
didn't at the time).  He noticed that the comment didn't match the code -- the
parameter should have been ABC_ISL_RR.  Because of this, my code wasn't running
with the isolation level it had been designed for, hence the intermittent
failures.  With that fixed, the problem, and the biggest threat to the project,
went away.

The story has a happy ending: we did manage to get enough delivered to the
customer that they could open the spin-off on the date they had set.  They made
money on it.  So they were happy with us, and stayed with us for further
developments, so we also made money, and eventually the project showed a
profit.  We did get an entry into the new market segment, and the company (who
I left ages ago, though I stayed for some years after the time of this story)
went on to make lots of money and expanded considerably.

And the moral of the story ?  It could be something about project planning, it
could be something about proper choice of identifiers, but I think that it also
shows just how valuable commentary can be, and especially that redundant
comments are a Bloody Good Thing.

    -- chris

<snip>
>     /*
>      * set the isolation level to read-repeatability; that's the default
>      * anyway, but just to be sure
>      */
>     if (abc_set_is_lvl(db, ABC_ISL_RP) != ABC_OK)
>         ...
</snip>

 I think I sit firmly on the fence.  I feel a comment here was not
redundant - there is nothing obvious about the fact "abc_set_is_lvl" is
setting the isolation level of a relational database (well, perhaps the
context around it), nor is it at all obvious that "ABC_ISL_RR" vs.
"ABC_ISL_RP" means repeatable read.  Kudos for you for documenting the
arcane nature of these variables.

The "you don't need comments" camp (and I think you need class level
comments anyway, plus a good class diagram, plus a class library overview)
has a lot of it's genesis in the Smalltalk world.  It might be easier to do
in Smalltalk than C, although a lot of the lessons I've learned in Smalltalk
might potentially be utilized in C.

For argument's sake, let's say we have a class that represents the database
connection: DBConnection, that wrapped the calls to the DB library.  Then,
you would have written something like:

==============
logonWithUser: aString password: aString2

... various logon stuff here ....

    self setRepeatableRead.

...
==============
setRepeatableRead

    self setIsolationLevel: RepeatableRead

==============
setIsolationLevel: anIsolationConstant
    | result |

    result := self database isolationLevel: anIsolationConstant.

    result = OK ifFalse: [self dberror: 'Set Isolation Level Failed']

==============

Now you would have to check that your pool of DB Constants was correct:

OK=0
NonRepeatableRead=>0
RepeatableRead=>4

or whatever.  The pool creation code *should be documented*, because this is
where you touch the external system and where the "cryptic code to self
documenting pool variable" mapping occurs.

Smalltalk, with it's keyword parameters, lends itself to documenting what
methods do in the method naming.  Its flexible refactoring makes it easy to
break chunks of code into methods that, in turn, name what they do
(especially any Smalltalk with the Refactoring Browser, like D5).

Just my 0.02 - and thanks for sharing your experience - I find this topic
very interesting.  I often wonder how much I can take my Smalltalk
experience reducing comments to other languages - I just did a
VisualBasic.Net project and found some difficulties (overloaded method names
comes to mind) but also was able to use many of the techniques I had
developed writing Smalltalk.

jlo

"Kirk W. Fraser" <[hidden email]> wrote in message news:<eEuB9.26967$A%[hidden email]>...
> Further discussion on documentation that would actually help make
> programming easier is encouraged!!!

This thread seems to be about how one should write class comments. To
my mind, "documentation" is something broader. It may include class
and method comments, but it also includes user's guides, tutorials,
API descriptions, reference guides, tools reference, on-line help,
etc.

What audience are you trying to reach? Experienced programmers?
Beginners? Class comments are not really the place to try to reach
beginners. If the goal of making programming "easier" means "making
programming easier for beginners", then it might be worth thinking
about other forms of documentation that are directed at a broad
audience.

For example, consider the books offered by a publisher like O'Reilly &
Associates, and look at the titles for PHP and Python. What would it
take to get a similar title published for Smalltalk?

M. Roberts

Jeffrey,

<grin>

> I feel a comment here was not
> redundant - there is nothing obvious about the fact "abc_set_is_lvl" is
> setting the isolation level of a relational database

As I look back on it I agree, but at the time, when the code, and I, and my
colleges, were all steeped in the API to the database, it certainly felt
redundant.  I wouldn't have used the comment if it weren't for my habit of
commenting code so that it can be followed *without* reading the code.  (We're
talking about C, here, -- I work slightly differently in Smalltalk).

> For argument's sake, let's say we have a class that represents the database
> connection: DBConnection, that wrapped the calls to the DB library.  Then,
> you would have written something like: [snip]

For comparison, here's how it might turn out if I were coding it:

==============
setRepeatableRead
    "set the database connection's isolation-level to 'repeatable read'.
    Note that changing the isolation level will close any open cursors.
    Also note that this mode is the default for a newly opened connection"

    self setIsolationLevel: ABC_ISL_RR.
==============
setIsolationLevel: anInteger
    "private -- set the connection's isolation level to one of the
    modes defined by ABC_ISL_* constants"

    (self database isolationLevel: anInteger = ABC_OK)
        ifFalse: [self dberror: 'Set Isolation Level Failed'].
==============

One minor difference is that I prefer to use the documented names of
third-party constants at the bottom-most level, which both adds to and reduces
the self-documenting effect.

You'll notice that the comment on #setIsolationLevel: is almost redundant.  I
agree that it is.  However it helps me make a point -- if I weren't in the
habit of commenting *all* methods, then I'd probably not have commented that
one, but I *also* (not being in the habit) probably wouldn't have thought to
comment #setRepeatableRead either, and its comment is definitely not
unnecessary.

> Smalltalk, with it's keyword parameters, lends itself to documenting what
> methods do in the method naming.

Yes I agree with this, and the method name does provide a useful source of the
redundancy that I was advocating.  However, in the example above, to get a
reasonable level of self-documentation, I think that the method would have to
be renamed to either #setConnectionIsolationLevelToReadRepeatability, or
#setIsolationLevelToReadRepeatability (depending on which it actually did).  It
could be argued that these are better method names anyway, but for my taste
they are too long and carry too much explicit context around with them, extra
baggage that makes the sender code clumsy.

Since you've said you are interested in this topic, I'll risk a further
tangential waffle.

I suspect that the "top-down", or "caller-driven", way of working leads
naturally to a tendency not to comment code much.  If you are using
programming-in-the-debugger, or are doing test-driven coding, then whenever you
reach the point of writing a particular method, you will naturally have a
complete "context" in the foreground of your awareness.  You'll have a complete
picture of what responsibility the method is intended to discharge, and what
the dynamic call sequence is that reaches the method.  This is information that
the *reader* of the code won't have (unless they are using the debugger to
explore the code).  I suspect that as a result the "top-down" programmer will
tend to document less of that context, either because it is so obvious *to
him*, or (if he believes in the value of comments and is being conscientious)
because doing so provides no real value to him at the time -- i.e. the comment
is all cost, no personal benefit.

I don't like the caller-driven way of programming myself (I've nothing against
other people who use it -- except the above suspicion -- but I find it hampers
my ability to create abstractions).  I like to conceive a "role" or a set of
responsibilities" and create a class or group of classes that constitute a
machine for discharging those sorts of responsibilities.  Later on, I'll write
higher-level code that makes use of that machine.  That means that when I'm
coding any particular method, my focus is more on the way*s* it is intended to
be used, since I am -- by creating the method -- attempting to design a
facility for others (and me) to use.  Since that's how I'm thinking, I don't
find that commenting a method is a nett cost (usually).  The comment is not
only there for other people to read, but is also there as my "working notes" on
my design as it evolves.  The comment helps me to think, and as such is a
benefit to me personally and immediately.

Anyway, getting sort of back on topic, that's part of the reason that I don't
have a lot of sympathy for Andy's position that providing decent method
comments is "too expensive".  (I agree entirely that "glossy" documentation
would be an unwarranted waste of resources, however.)

    -- chris

Interesting ideas - I think I fall in
<snip>
> I suspect that the "top-down", or "caller-driven", way of working leads
> naturally to a tendency not to comment code much.  If you are using
> programming-in-the-debugger, or are doing test-driven coding, then
whenever you
> reach the point of writing a particular method, you will naturally have a
> complete "context" in the foreground of your awareness.  You'll have a
complete
> picture of what responsibility the method is intended to discharge, and
what
> the dynamic call sequence is that reaches the method.  This is information
that
> the *reader* of the code won't have (unless they are using the debugger to
> explore the code).  I suspect that as a result the "top-down" programmer
will
> tend to document less of that context, either because it is so obvious *to
> him*, or (if he believes in the value of comments and is being
conscientious)
> because doing so provides no real value to him at the time -- i.e. the
comment
> is all cost, no personal benefit.
>
> I don't like the caller-driven way of programming myself (I've nothing
against
> other people who use it -- except the above suspicion -- but I find it
hampers
> my ability to create abstractions).  I like to conceive a "role" or a set
of
> responsibilities" and create a class or group of classes that constitute a
> machine for discharging those sorts of responsibilities.  Later on, I'll
write
> higher-level code that makes use of that machine.  That means that when
I'm
> coding any particular method, my focus is more on the way*s* it is
intended to
> be used, since I am -- by creating the method -- attempting to design a
> facility for others (and me) to use.  Since that's how I'm thinking, I
don't
> find that commenting a method is a nett cost (usually).  The comment is
not
> only there for other people to read, but is also there as my "working
notes" on
> my design as it evolves.  The comment helps me to think, and as such is a
> benefit to me personally and immediately.
>
<snip>

In Smalltalk, I fid myself creating a picture of the class and/or group of
classes, but once I find myself on one particular class, I tend to be top
down.  I don't think this leads to less comments by nature of "knowing where
I am at the time", but I do think it leads needing less comments.

That's why I think a group of classes needs a "subsystem" description (think
Ken Beck's original SUnit write-up - short, but without it you would have a
harder time using it) and a class comment is a good idea for all classes.
After that, method comments are as necessary.

However, I'd always rather have my folks err on the side of too may comments
than too few ;>

jlo

People tell me they find my code readable, and sometimes it does not

Chris,

It surprises me greatly how C programmers (including me up until I learned Smalltalk)
are willing to use "unwrapped" functions and constants like this.  In any mission
critical development I would have to recommend some sort of abstraction level or
at least a simple remapping of these abbreviations to something more meaningful, much
in the way that your Smalltalk examples show.  This should result in "executable
comments" that by design may not become obsolete.  For example, the original

#include "abc.h"
if (abc_set_is_lvl(db, ABC_ISL_RP) != ABC_OK)

could be turned into

#include "myabc.h"
if (abc_set_isolation_level(db,ABC_ISOLATION_LEVEL_READ_REPEATABLE)!=ABC_OK)

with myabc.h containing

#include "abc.h"
#define ABC_ISOLATION_LEVEL_READ_REPEATABLE ABC_ISL_RP
int abc_set_isolation_level(DB db,int isolation_level);

and somewhere such as myabc.c

#include "myabc.h"
int abc_set_isolation_level(DB db,int isolation_level)
{
   return abc_set_is_lvl(db,isolation_level);
}

That doesn't seem to be the C way, but it might work better.  If the one level of
indirection is too expensive for production, then after everything is debugged, change

int abc_set_isolation_level(DB db,int isolation_level);

to

#define abc_set_isolation_level abc_set_is_lvl


Keith


Chris Uppal wrote:
>

[snip]

[snip]
 
>     -- chris

I tend to like the idea of enough documentation that you don't have to read
the code, especially for arcane classes where I don't know what is going on
at first.  That implies both class and method comments.

As a Smalltalker, I know every class has methods which communicate with each
other by message passing, parameter calls, and so on.  It is like a pre-mix
framework to build a personalized house on.  Once you have analysed your
problem enough to create a reasonable set of classes, instance variables,
and methods, then it gets back to good old coding with generate and test to
mesh the working code around the framework of classes and methods.  So we
could identify in comments what the framework is supposed to do with
readable comments long before it actually works.

XP's emphasis on refactoring tells me that we should change the framework
often until we reach a working solution.  The idea is to better integrate
the code which does the real work with the framework to minimize everything.
With very meaningful class and method names, this would reduce the need for
explicit comments.  But for the newbie to a package, whether it is part of
Dolphin's base classes or something purchased from a third party like ST3D,
there is still considerable need to be introduced to what is going on.

Take ActiveX for example.  As posted in another thread, I know nothing about
it.  I am told that working with it is the way to get my webcam to send its
pictures into Smalltalk for processing.  I can argue the language developers
"should" provide integrated access to all common peripherals as a standard
feature but that won't make it happen.  So I have to learn to use ActiveX.
Take a look at the ActiveX classes.  If you don't know anything about
ActiveX, you need new programmer information, not "developer" information.
You certianly don't care that Beck's best practices were performed in
creating those classes which makes them self-documenting to those who are in
the know about ActiveX.  You need simple step by step newbie level
documentation on how to use the features available.  So consider the
reader -- if anyone needs to read the documentation, they probably need a
great deal of help.  If they just need a refresher, they can employ speed
reading.  There should not really be a difference in documentation levels
for different users, preschool or Ph.D..

Some documenters make a big difference in documentation over time.  I once
worked on an old CDC mainframe to convert to IBM and I found that early
operating system manuals were very helpful on the basics while later manuals
were helpful on the new advanced features but ignored discussing the basics.
I would of course like to see both covered well.  The manuals themselves
didn't make me a whiz at upgrading systems prior to conversion but they sure
helped.  Another thing that helped was being able to look in all the user's
private code to discover new ideas that might not be documented elsewhere.
Unfortunately this is very difficult in extended professional communities --
if people don't want to share their toys you have to find some other way to
learn to play.  And you're hobbled with copyright restrictions, licensing,
etc. to where it can become expedient to start your own language.

So I certianly agree with the crowd that has little or no sympathy for
Andy's position that providing decent method comments is "too expensive" as
Chris put it.  And I don't need to see 10 different flavors of
documentation, spread over tutorials, classes, methods, manuals, help, and
so on.  I would like to see it all in one easy to access place.  And as an
example to users to encourage them to write thiers, I believe the best place
for this documentation is right in the code or the method comments.  If
users have to go through a slow approval process to get their comments into
the next version's helpfile or tutorial, that's too slow.  The community
should be able to share comments here on the newsgroup just as they can
share code and other help.

Dolphineers,

While I wouldn't mind having more and better class comments to read, getting them
seems to be just a question of putting in a little more work to write them.  My
priority instead would be to add a mechanism to document class and instance
variables in a way that could be easily maintained and updated, which would be more
of a design and standards problem.  Describing variables in the class comment is
not such a way.  In many languages, one can do this (forgive the poor example):

int bufferIndex;          // Formerly known as i
static int bufferSize;    // Limit this to 16K according to RTF specification
static char *buffer;      // Pointer to char array of size bufferSize

In Smalltalk you could do the following, but of course the comments are forgotten
except for a record in the change log.

MyObject subclass: #Object
   instanceVariableNames: 'bufferIndex'   "Formerly known as i."
   classVariableNames:
      'BufferSize' ,   "Limit this to 16K according to RTF specification."
      'Buffer'         "Pointer to char array of size BufferSize."
   poolDictionaries: ''
   classInstanceVariableNames: ''

If the comments are written to the class comment instead, that information will be
obsolete if ever the variable names change or some get deleted or added, etc.

Instead, why not make a method that takes not a space separated list of variables
but an ordered collection of associations between a variable name and a comment?  
This method can collect the variable names into a string and forward it to the
normal #subclass:instanceVariableNames:... method.  It also keeps the variable
comments around for later use.  For example, in the class browser it shows the
comments underneath the class definition in comment like this:

MyObject subclass: #Object
   instanceVariableNames: 'bufferIndex'
   classVariableNames: 'BufferSize Buffer'
   poolDictionaries: ''
   classInstanceVariableNames: ''
"
bufferIndex - Formerly known as i.
BufferSize - Limit this to 16K according to RTF specification.
Buffer - Pointer to char array of size BufferSize.
"

A dialog was recently added to Dolphin for adding a class.  An additional dialog
could be used for editing a class.  (Editing the strings which have to be re-parsed
for every change is primitive, isn't it?)  It could support the reordering,
insertion, and deletion of variables, displaying the variables in the parent class,
listing potential pool dictionaries, and, of course, displaying and editing the
variable comments.  Anytime a variable was changed, the comments would change with
it.  When a variable gets added, the UI would nag you for a comment.

Comments, anyone :-)


Keith



Kirk W. Fraser wrote:

Hello all,

I'm less worried about documenting instance variables for a few of reasons:
(1) they can have different meanings at different times; (2) they are
typically hidden state that shouldn't be of much interest unless one is
really paying attention to or modifying the details of the methods (so good
comments therein should be more helpful); (3) I'd rather see an author of a
class write a comment about how/when/why I would use the class.

FWIW, I'm finding that a good package comment is typically of the most use
to me in (re)understanding my own frameworks.  That's in part because it's
the first thing I see when I invoke my package documentation system, and
because classes often work together, so the package/framework level is a
good place to write how-to documentation.

Have a good one,

Bill

--
Wilhelm K. Schwab, Ph.D.
[hidden email]

[for some reason OE is playing up trying to post this.  Apologies if you see it
several times.  Or not at all ;-) ]

Keith,

> It surprises me greatly how C programmers (including me up until I learned
Smalltalk)
> are willing to use "unwrapped" functions and constants like this.

I don't want to come across as defensive (after all, why would I want to defend
a poxy, jumped-up, young C programmer ? ;-) but the code *was* part of my
wrapper layer...

    -- chris

[hidden email] (M. Roberts) writes:

> For example, consider the books offered by a publisher like O'Reilly &
>
> Associates, and look at the titles for PHP and Python. What would it
> take to get a similar title published for Smalltalk?

An example of good documention is the Python library documentation. It
is just a set of HTML files, but it describes all the packages that is
included with Python, gives a short description of all classes and
methods, and some small trivial examples on how to use them. I think
that Dolphin users could benefit from this, as I know that the
documentation helped and helps me a great deal when I am programming
Python.

Anyone interested in viewing the python documentation can go to
www.python.org

--

Vennlig hilsen

Syver Enstad

You are too honest ;>


"Chris Uppal" <[hidden email]> wrote in message
news:3dda5994$0$114$[hidden email]...
> [for some reason OE is playing up trying to post this.  Apologies if you
see it
> several times.  Or not at all ;-) ]
>
> Keith,
>
> > It surprises me greatly how C programmers (including me up until I
learned
> Smalltalk)
> > are willing to use "unwrapped" functions and constants like this.
>
> I don't want to come across as defensive (after all, why would I want to
defend
> a poxy, jumped-up, young C programmer ? ;-) but the code *was* part of my
> wrapper layer...
>
>     -- chris
>
>

Andy & Blair,

The discussion on documentation has hushed and to me the biggest observation
is so few were interested in the topic when I also posted an invitation on
the other newsgroup.  So maybe there is not much market for documentation.
The lessons collected from everyone include:

>From C.L.S. Patterns thread:
A) Design documentation is only needed if users are expected to modify code.
B) There is no excuse for not having good application user documentation.
Example: Provide documentation on how to use D.5 ActiveX code to link to
services, not on how the code was designed.
C) Patterns may help improve code beauty, elegance, and style but do not
solve problems.

>From C.L.S.D. Documentation thread:
A) Documentation consumes time whether done by vendor or in the heads of
users and dispensed through the newsgroup instead of the product.
B) Both preschool and developer level documentation can be integrated in
class comments.
C) The Wiki is unreliable (loses information) so its users have abandon it.
D) Types of desireable class documentation being aware to make it useful,
not just a boring checklist that results in useless information:
1) A practical statement about why the class exists.  (This statement should
not require update work for new releases).
2) How to immediately use the class stand-alone in interesting ways.
3) How the class is used in combination with other classes.
4) Usage assumptions - what must be true to make it work.

E) Full documentation can include class and method comments, user's guides,
tutorials, API descriptions, reference guides, tools reference, on-line
help, etc.
F) A more complete Dolphin book could be written -- see PHP & Python books.
G) HTML is a good alternative documentaton delivery system.
H) Tutorial and developer comments can be seperated (EXCEPT tutorials show
only one way of doing things instead of an explaining all ways including the
one you happen to need).
I) Perhaps the reason for dismissing method comments is for lack of having
seen some good ones that were actually helpful i.e. a self-fulfilling
prophecy.
J) Making sure documentation and code agree sometimes saves the code!
K) People have claimed languages were self-documenting since the days of
COBOL and it only true in trivial examples which people already understand.
L) Test driven programming doesn't naturally fit with documenting but that
implies incomplete analysis - schools teach adequate analysis before coding
takes no more time and can produce better results.  Analysis is compatible
with having enough documentation you don't have to read the code.  (It may
be the difference between programming and hacking).
M) It is interesting the D.5 line is named XP and provides a refactoring
browser yet little or nothing of Kent Beck's methodology is either explained
or footnoted with a book citation.  Is this an example of going extreme at
not documenting?
N) It's better to error on the side of too many comments than too few.
O) It could aid the existance of class documentation to cause the browser
pop-up to provide space for it (require a non-blank entry) when creating
classes.
P) Whether provided at the package, class, or method level, a clear
statement on how/when/why to use a piece of code is a good thing.

Thanks to all for your input to this discussion.  If your remarks aren't
adequately summarized here, tell me.  There are a lot of good ideas.  I was
also surprized no one provided other examples to help document everyone's
image.  Further analysis of these ideas I think could lead to a reasonable
standard for Andy and Blair which would not be too costly for them to
generate or maintain.  In the interest of proposing a low-cost documentation
system for them, here is another analysis pass:

--------Low Impact Documentation----------

Andy and Blair are requested to give a wee bit more attention to
documentation.  To make it as wee as practical, please add an editor to the
class creation pop-up window that feeds the class comment holder, requiring
non-blank entries to:
1) Why is class needed?
2) When would it be used?
3) How can it be used?

This simple editing feature should be integrated with the refactoring
browser to save  comment integrity over class name changes.  This update
should exist in Andy & Blair's development image even if the tool is not
sent out in a release update for others.  It of course can be defeated but I
hope it gets the idea across and would serve as a reminder.

Sincerely,
Kirk W. Fraser