phoneNumber
    "return the phone number instance variable"
    ^phoneNumber

In this case, I can read the code faster than the comment and I'm
guaranteed that the code is accurate.

Having added a method comment, you should ask yourself why the method
needs a comment to make it understandable.  You can then simplify,
shorten, and clarify the method until it is so clear that it no longer
needs a comment.

Method comments can be a code smell.  They indicate that the code itself
isn't clear enough.  Once it is clear enough, you can remove the comment
because it's superfluous.

I did a quick spot check of Dolphin class comments - and I would agree that
they add some benefit.

On the method side however, comments are more often than not a crutch to
not renaming things. For example here's a random method I plucked out of
DBAbstractRow in dolphin:

isDeletedRow
        "Answer whether the receiver represents a row in a result set which has
been
        deleted in the time since the result set was originally queried."

        ^self status = SQL_ROW_DELETED

So the deleted aspect is covered by the name, the interesting bit is the
"since the result set was orginally queeried" - which kind of makes me think
that the real smell is the name - maybe #isDeletedSinceQueried would be better?
And this is the problem with comments, rather than doing the right thing,
people often just add a comment.

I did an experiement a few years ago - a colleague and I wrote comments for
a week, while we refactored code and built up a system. At the end of the
week, most of the comments we checked were either wrong, or misleading -
the problem is that the overhead of keeping them upto date is quite high
- especially if you constantly simplify and refactor/rename. The refactoring
tools will happily rename references for you - but comments aren't references
(so if you are commenting - keep that in mind, and maybe keep comments as
small as possible).

The other aspect - at least for me, is that the tests are often much better
comments than the comments. However in Smalltalk, because things are so natural
to just "do it" there doesn't seem to be lots of examples of well tested
(read descriptive) libraries. I was pleasantly suprised to find some in Swazoo
- and the tests did actually help me figure out how to get things running.
However in this case, a high level overview of how to do it right was missing
(in fact I think you sent me a few things to show swazoo in action) - so
maybe a good overview is more helpful than itty bitty comments.

Good point overall though - I will look at my latest library and see if there
are any things I could helpfully do to make sure its understandable.

Even if the code really is well-written enough that it is its own
documentation, we still need some pointer as to which classes to look
at first.

Those are my comments as a user of goodies. As a provider, I know I
fail my own tests sometimes :-(.

Most Smalltalk methods can be understood by reading the code, but in a
complex app, where the method fits into the bigger picture is not always
easy it understand.  And a comment about the intent of a method is less
likely to become outdated.  Even if code is refactored, the reason it was
added in the first place is probably still valid.

macta escribió:

Doing TDD one first sends a message with the selector expected, but
once a MNU exception is thrown and one chooses to implement the
method, the first to write is the comment, not its implementation, IMHO.

But it doesn't apply for exploratory or self learning usage, which
is the way most smalltalkers uses an Smalltalk (or at least used to do).

Regards,

David Buck escribió:

The comment should say anything about the implementation, I must be
able to program "trusting" in the comment (as I trust in the type),
if I read that #rounded answers me the receiver rounded, I don't
care how is it implemented. In many cases the selector is intention
revealing enoguh (as in my example).

About getters and setters, it's true that are the most obvious case,
  but for the sake of homogeneity they should be there, after all
they're simple to write, and most Smalltalks (at least Dolphin
does), allows you to create the accessors for the i.v. automatically.

Object>>name
        "Answers the name of receiver."

Fast coding isn't related to better coding, IMHO.

Regards,

Method comments are often the only guide to an API in a class. When
they are lacking, the developer may be forced to spend more time trying
to figure out the API itself. The Smalltalk language provides no fixed
convention to distinguish public from private methods, and it doesn't
have the notion of an interface.

Without a clearly-expressed API, an application programmer is soon
combing through all the protocols, looking for suitable-sounding
selectors. Without adequate method comments, she must reverse-engineer
methods inside the library. Reading method after method to figure out
all the conditions under which they return true/false/nil/whatever can
be a big waste of time.

There's a lot of talk about how XP can be used to eliminate the need
for comments, but I personally don't find these claims terribly
persuasive.

First, having tried to work with code that was developed this way, it
strikes me (and I am not alone) that no matter what the XP theory says,
the reality is that all bets are off when the next developer who looks
at your code isn't pair programming with you. Passing on undocumented
code may be passing on the work of actually making it clear, and it
presupposes that the next person who didn't develop the code is going
to readily grasp its design by reading code.

Yet, just because developer A thinks the intention behind a class is
obvious is clearly no guarantee that developers B, C, and D will feel
the same way. Similarly, there is no guarantee that the next developer
looking at the code will have the same level of expertise. We easily
say "read the code" when in practice this often means
reverse-engineering it.

For example, let's say you want to build a CodeTool in the Refactoring
Browser that needs to read the current state of the RB navigator. Is
there a clear API for this? No. The RB was developed XP-style, and the
idea seems to be that it's not necessary to present an API through
comments. "But it's simple, just go read the code." Right? Err, not
quite. At first, it seems straightforward, but there are inner
mechanisms which are undocumented and non-obvious. In fact, a seasoned
Smalltalk developer working for Cincom spent 75 hours
reverse-engineering that one particular interface. If it took 75 hours
to figure out how to get the current browser selection, it's not
"simple". Also, that was time spent just to figure out how to use the
RB code, not to write the missing documentation. So, another developer
can go through the same hassle again next time.

In my experience, a developer who didn't write the code in the first
place will be quite reluctant to write documentation for it. You know
the feeling: "do I *really* understand what's going on here? Do I
understand it well enough to document it?" Thus, once it leaves the
hands of the original authors, it becomes much harder to add lacking
documentation later.

Another claim is that comments "should be unnecessary" and that methods
should be re-factored until they are simple enough not to need
comments. If we accept this, then can we apply this practice to all the
existing classes in the base library that "need" comments? And what of
all the opaque code that doesn't even have comments in the first place?

Well, how many man-years of work are we talking about here? How many
classes are in the base image? How many of them don't even have enough
comments to aid in simplifying the code in the first place? Do any of
the Smalltalk vendors have the resources to go through their base
libraries, simplify, shorten, re-write and clarify all of the code
until it doesn't "need" comments? The answer is pretty obviously "no".

As for the question about why developers don't comment, I can only
hazard a few ideas. Often, the design of the code changes several times
during development, and it's a nuisance to keep updating the comments
to track these changes. The idea is that when the code is "finished"
then the documentation will be written, but often that last step is
never taken. Documentation/comments are not seen as "deliverables". Or
else comments are unpleasant to write, they don't provide the same
enjoyment that coding does, so developers invent rationalizations to
convince themselves that comments are unnecessary. Another problem is
that a developer may look at a piece of code, find that the existing
comment is outdated or inadequate, and after a while conclude that the
comments aren't very useful -- a vicious cycle.

Overall, as long as writing documentation/comments is not viewed as an
essential part of the code development process, they'll likely be
forgotten or otherwise rationalized away.

Some will argue with these points, citing the usual counterexamples of
code that is overly encumbered with comments, etc. Certainly, that is a
problem, and setting the standard too high means too much work to
maintain the "excess" documentation. I won't argue with that.

Rather, my concern is closer to Mr. Maringolo's, i.e., not with code
that has "too much" commentary, but with code that has too little.
I.e., code that lacks clear APIs, or the basics like package and class
comments for the main components or public classes of an
application/subsystem. This is the case where the application developer
is forced to reverse-engineer code.

Clearly, developers are leery of the cost of spending a lot of time
writing and maintaining comments under "verbose" methodologies, but
what about the deferred costs of producing incomprehensible code, code
that demands a prohibitive time investment to use?

A balance must be struck between too much and too little.

At Cincom, we decided to address these issues with an internal policy
that all new code going into the product should be adequately
commented, and we launched an initiative called SmalltalkDoc that aims
to provide better API documentation for the base library.

Some have argued that the Smalltalk vendors should try to formalize the
notion of an interface, perhaps along the lines of SmallInterfaces. My
own preference has been to do this through an integrated documentation
approach like SmalltalkDoc, which doesn't burden the developer as much.
The general idea is to provide a framework, some automation and better
tools, all with the aim to make it easier to write and maintain
high-quality comments and API documentation.

For the curious, more information on SmalltalkDoc is available here:

http://www.cincomsmalltalk.com/CincomSmalltalkWiki/SmalltalkDoc

Regards,

Personally, I have never encountered (in real life) a programmer who wanted to
avoid comments (for any of the "reasons" you mentioned), who didn't have an
over-inflated idea of the quality of his own code.

A) Who /cares/ whether the number is stored in an instvar ?

B) It's a good deal less obvious than it looks -- or at least it might be.
Consider this:

    phoneNumber
        "answer the phone number as a String of digits.
        Note that non-digit characters may be included either as
        separators, or in order to indicate hybrid local/international
        numbers.
        For instance:
             +44 (0) 1628 589262
        "
        ^ phoneNumber.

I often write the comment prior to the code, being a part of the
structuring and modelling excercise.

As James Robertson pointed out, a communication problem specific to
Smalltalk is, that even straight forward code tends to spread its
functionality across several classes, which is not necessarily unveiling
the original intention of "the algorithm" behind it at a glance. This
finer granularity makes Smalltalk maintainable and extensible on the one
hand, but harder to read on the other hand.

I'd like to see clearly visible levels of method "privacy":

1 "private": used only by the instance or class itself
2 "intimate": used among closely related classes
3 "public": API available to everyone, likely to survive future releases
4 "entry": API for suggested top-level entry points, e.g. start or
shutdown a server, open a window, run an example, etc.

I have no idea how to indicate these levels in the IDE (colors?
filters?), but IMHO browsing a package with a "show only entry methods"
option would dramatically speed up the task of exploring other people's
code.

If I'm writing an application, I can work much more effectively if the
code I want to use has good class comments, a clearly-expressed API,
and method comments that explain the function of the method, what it
returns, any exceptional conditions that might arise, etc.

If the code in question lacks all of this and I'm expected to read the
tests, it's still a nuisance. In order to use the code, I must go off
and find the tests, load them, try and figure out which classes test
the methods in question. Basically, I'm clicking on "senders" over and
over, then reading a bunch of test methods, usually skipping all of the
initialization junk in the beginning of the test method, etc. I'm still
reading code to try and reconstruct the API definition of the class.

While I think TDD is a great idea, reading over a bunch of tests is
much less efficient than having well-written API documentation.

For those interested, I wrote a proposal several years back that
explores these issues in a bit more detail:

http://www.cincomsmalltalk.com/CincomSmalltalkWiki/Documentation+Stan...

Regards,

My experience is that method comments are "invisible".

When intensively working to solve a problem our programmers only see the
code, they literally don't see the method comments.
As a consequence our image is littered with method comments like "Dummy
method template.  This was installed by the debugger define method
command.",  the programmers really don't see them, only when I point it out
does it enter their consciousness.

Apparently at the development stage method comments don't add value,
programmers block them out. Architecture is communicated differently,
mostly by pairing in our shop.

That's really what they are: design notes. Maybe they belong with
the code, maybe they don't. If the code is not immediately clear,
but is well written, then you need to refer to design notes. It may
be convenient to have them right there, as code comments, but I don't
see a definitive argument that all code must have code comments.

Just my two cents.

First, remember that Smalltalk has no concept of an interface and makes
no distinction between public and private methods. The Smalltalk
language has no built-in support for expressing an API, and even the
conventions for naming protocols are *not* consistent across the
system. Method comments are sometimes the *only* information that
really distinguishes the public from private in a class. They are not
just design notes. They serve a role in defining the public interface
to the class.

You can, of course, choose not to follow these conventions, you don't
have to include method comments. However, this is deferring a cost.
Each developer who uses the class Z must now read over all of the code
to mentally reconstruct the API, and thus the time and effort required
to use Z go way up.

Remember also that the writers who produce documentation use method
comments to produce API or subsystem documentation. They need to know
what's public and what's not. If you don't include those comments, then
in practice the work flow breaks down. Writers do not always have the
time or training to reverse-engineer undocumented code. Often, the
documentation can't get written until the original developer can be
consulted to "explain" the class. This means sending e-mail messages
and opening job tickets just to get some basic information. If the
original developer left the company, the writers demote the priority of
that project because it takes too much time. No comments = work doesn't
get done. I can tell you from personal experience that all of this is a
*huge* waste of time.

Second, if comments are not "with the code", then it is more work (more
clicks, more hunting, typing, etc) to keep them maintained, more work
to use them later, more chance that the "notes" get lost or out of sync
with the code. Separating them also means it takes more attention to
focus on both comments and code at once. More attention means more
effort. Attention/focus are fundamental issues in the organization of a
system and the design of its tools.

In the VisualWorks browser, for example, we have always had a separate
code pane to show class comments. After many years of working with this
design, we are now dissatisfied with it. Why? It separates comments
from code. It is the seasoned opinion of our tools designer that we
need a better solution that doesn't force a separation between the two.

Next, "if the code is not immediately clear" - for who? The
implementor or the developers who want to use the code? These are often
not the same person and they often have totally different levels of
expertise. What is "clear" to one is often not at all clear to the
other, and the implementor is often a poor judge of what is clear for
others. This is part of the reason that there are "code reviews" that
involve several different people.

Finally, I would say that the argument is not that *all* code must have
comments, but that the code becomes more usable when comments are used
judiciously in public methods, and the cost of using the code goes
down. In private methods, comments can be used to capture the intention
of the design (as Bob Nemec put it in another part of this discussion,
they should express "the 'why', not the 'how'"), and this helps to make
it more maintainable in the future.

If you're running a small, closed shop, then maybe this doesn't matter.
But if the code is to be used by somebody in another group, outside
your shop, then it could be a problem.