Home > Archive > Smalltalk > April 2006 > About method comments
You are viewing an archived Text-only version of the thread.
To view this thread in it's original format and/or if you want to reply to
this thread please [click here]
| Author |
About method comments
|
|
| Esteban A. Maringolo 2006-02-28, 7:03 pm |
| Hi all:
On thing that disturbs me everytime I see a presentation/screencast
or download some goodie, is the total lack of method/class comments.
Particulary on third party classes, but I find it also on many base
classes of some smalltalk distributions.
The only smalltalk which I can tell it has comments for almost all
the methods and classes is Dolphin. But this isn't true for many
goodies around.
Am I the only who worries about this, or also concerns somebody else?
For those who don't comment, why? :-)
Regards,
--
Esteban
| |
| Chris Uppal 2006-02-28, 7:03 pm |
| Esteban A. Maringolo wrote:
> On thing that disturbs me everytime I see a presentation/screencast
> or download some goodie, is the total lack of method/class comments.
>
> Particulary on third party classes, but I find it also on many base
> classes of some smalltalk distributions.
[...]
> Am I the only who worries about this, or also concerns somebody else?
You are not alone.
-- chris
| |
| Thomas Gagne 2006-02-28, 7:03 pm |
| I like the way stx does it's comments. Comments on a class are added to
method inside "comment" method categories. While working on a class
you're always reminded you haven't commented it if the method category
is empty.
| |
| David Buck 2006-02-28, 9:57 pm |
| Esteban A. Maringolo wrote:
> Hi all:
>
> On thing that disturbs me everytime I see a presentation/screencast or
> download some goodie, is the total lack of method/class comments.
>
> Particulary on third party classes, but I find it also on many base
> classes of some smalltalk distributions.
>
> The only smalltalk which I can tell it has comments for almost all the
> methods and classes is Dolphin. But this isn't true for many goodies
> around.
>
> Am I the only who worries about this, or also concerns somebody else?
>
> For those who don't comment, why? :-)
You should definitely have method comments if the method comment helps
you understand what the method does. I don't like seeing this:
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.
David Buck
Simberon Inc.
www.simberon.com
| |
| Ian Upright 2006-03-01, 7:58 am |
| "Esteban A. Maringolo" <eMaringolo@small-REMOVETHIS-talking.net> wrote:
>Hi all:
>
>On thing that disturbs me everytime I see a presentation/screencast
>or download some goodie, is the total lack of method/class comments.
>
>Particulary on third party classes, but I find it also on many base
>classes of some smalltalk distributions.
>
>The only smalltalk which I can tell it has comments for almost all
>the methods and classes is Dolphin. But this isn't true for many
>goodies around.
>
>Am I the only who worries about this, or also concerns somebody else?
>
>For those who don't comment, why? :-)
I'll reserve my judgement and not comment on this. :-)
Ian
>
>Regards,
---
http://www.upright.net/ian/
| |
|
| IMHO, one should use method comments. However, I have been in situations
when the boss, also an st'r, integrated the stuff I wrote or took it over,
he removed all the method comments.
-g
| |
|
| Hi Esteban,
> Hi all:
>
> On thing that disturbs me everytime I see a presentation/screencast or
> download some goodie, is the total lack of method/class comments.
>
That said there are way too many bogus comments around (if you ever read
Sun JDK java doc you will know what I mean).
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 w , while we refactored code and built up a system. At the end of the
w, 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.
Tim
| |
| Steven Kelly 2006-03-01, 7:58 am |
| "Esteban A. Maringolo" <eMaringolo@small-REMOVETHIS-talking.net> wrote
in message news:D6Cdna08bJqA65nZnZ2dnUVZ_tOdnZ2d@to
tallyobjects.com...
> On thing that disturbs me everytime I see a presentation/screencast
> or download some goodie, is the total lack of method/class comments.
What irks me most is when there is no package/parcel comment. Second
worst is when there is no version comment on parcels. If these are
goodies, and are being maintained, it makes it many times easier to
use if there's at least some information on how to get started, and
what has changed since the last version.
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 :-(.
Steve
| |
| Steven Kelly 2006-03-01, 7:58 am |
| Oops, meant to say "second worst is when there is no version comment
on PACKAGES" - parcels rarely even have a strict version number. Mind
you, we were one of several people caught out when the SmaCC package
in the public store had a newer version number than the parcel in
/goodies/*, but was actually an older version...
S.
"Steven Kelly" <stevek@metacase.com> wrote in message
news:kIfNf.144$hR2.135@read3.inet.fi...
> "Esteban A. Maringolo" <eMaringolo@small-REMOVETHIS-talking.net>
> wrote in message
> news:D6Cdna08bJqA65nZnZ2dnUVZ_tOdnZ2d@to
tallyobjects.com...
>
> What irks me most is when there is no package/parcel comment. Second
> worst is when there is no version comment on packages [Edit]. If
> these are goodies, and are being maintained, it makes it many times
> easier to use if there's at least some information on how to get
> started, and what has changed since the last version.
>
> 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 :-(.
>
> Steve
>
| |
| Bob Nemec 2006-03-01, 7:58 am |
| > On thing that disturbs me everytime I see a presentation/screencast or
> download some goodie, is the total lack of method/class comments.
The rule that I follow is to comment intent, not action (the 'why', not the
'how').
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.
Bob Nemec
Northwater Objects
| |
| Esteban A. Maringolo 2006-03-01, 7:58 am |
| Hi macta,
macta escribió:
> Hi Esteban,
> That said there are way too many bogus comments around (if you ever read
> I did a quick spot check of Dolphin class comments - and I would agree
> that they add some benefit.
[SNIP]
> 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.
Yes, the method could had a more intention revealing selector. But
even in that case the comment should not be ommited.
> I did an experiement a few years ago - a colleague and I wrote comments
> for a w, while we refactored code and built up a system. At the end
> of the w, 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).
Well... many times if you refactor some method and need to modify
the comment may indicate that is was bad commented. The only problem
I see in the refactoring is when one changes the name of one or more
arguments, and those names are in the comment, but that is local to
the method and easily modifiable.
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.
> The other aspect - at least for me, is that the tests are often much
> better comments than the comments.
This proven to be true for documentation or usage purpose, and is so
because tests have gained momentum again during the last 2-3 years.
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).
> 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.
But here we are talking of another issue which is documentation of a
class, and more particulary of a set of classes and how to use them.
I agree with you that test cases are very instructive in how to get
started using something.
> 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.
:-)
Regards,
--
Esteban.
| |
| Esteban A. Maringolo 2006-03-01, 7:58 am |
| Hello David,
David Buck escribió:
> Esteban A. Maringolo wrote:
[color=darkred]
> You should definitely have method comments if the method comment helps
> you understand what the method does. I don't like seeing this:
> 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.
Agree, but that method is bad commented, because it never should
talk about its implementation. It should be something like "Answers
the phone number of receiver.", then if you refactor it to be
obtained from any other place than a i.v., the comment will keep
having meaning.
> 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.
I like the quote:
"Programs must be written for people to read,
and only incidentally for machines to execute."
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).
> 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.
Method comment _is not_ code comments, if the method talks about its
implementation, something smells. Method comment must complement or
expand the selector name itself, ignoring what the implementation is.
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,
--
Esteban.
| |
|
| The lack of method/class comments is a recognized problem. However,
comments missing from an application may be less serious than comments
missing from the class library in the base image.
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/Cinc...ki/SmalltalkDoc
Regards,
M. Roberts
Cincom Systems, Inc.
| |
| Chris Uppal 2006-03-01, 7:01 pm |
| mdr wrote:
> [...lots of sensible stuff snipped...]
I'm just picking up on one or two points.
> 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.
It seems to me that the pair-programming practise is intensely wasteful. No, I
don't mean the hypothetical halving of productivity. But every time the pair
communicate, "why do it like that?", "wouldn't X be better ?", "looks a bit
iffy to me", there's a good chance that that communication (or the answer)
should be in the code as a comment. Yet the information is passed to only one
other person...
> 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.
I don't see why anyone who is using commenting /properly/ -- i.e. as an
exercise in communication (with him/her self, with the next programmer, with
posterity) -- should have any difficulty with updating comments. If the code
is different, then clearly we'll have different things to say about it -- type
'em in !
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.
-- chris
| |
| Chris Uppal 2006-03-01, 7:01 pm |
| David Buck wrote:
> I don't like seeing this:
>
> phoneNumber
> "return the phone number instance variable"
> ^phoneNumber
Neither do I, but for different reasons.
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.
> 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.
Funny that, I see /lack/ of comments as a code smell. It hints to me that the
programmer is not thinking about the code, or is only thinking about it from a
single direction. There are many indicators that a programmer is not fully on
the ball (sloppy layout for instance), one of the strongest is that they are
not seeing the code as it will appear to the working system (and the working
programmer coming after), but only as it happened to appear to them at the
instant they wrote it. Tunnel vision can conceal an awful lot of ambiguity.
-- chris
| |
| Andre Schnoor 2006-03-01, 7:01 pm |
| I really can't imagine to not comment code at all. I absolutely need to
comment my code in order to understand it *myself* after a while. I more
than once encountered the situation that, when browsing through
classes/subsystems I wrote years ago, I found myself reverse engineering
my own stuff.
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.
Andre
| |
|
| >> The other aspect - at least for me, is that the tests are often much
[color=darkred]
>This proven to be true for documentation or usage purpose, and is so
>because tests have gained momentum again during the last 2-3 years.
>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).
While tests can be helpful for understanding code, I don't think they
are really an adequate substitute for a good comment on a public
method. Reading a test is still reading 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/Cinc...ndards+Proposal
Regards,
M. Roberts
Cincom Systems, Inc.
| |
| Reinout Heeck 2006-03-02, 3:58 am |
|
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.
R
-
| |
| Chris Uppal 2006-03-02, 7:57 am |
| Andre Schnoor wrote:
> I really can't imagine to not comment code at all. I absolutely need to
> comment my code in order to understand it *myself* after a while.
For me the need starts /as/ I write the code. The comments are, amongst other
things, my ongoing design notes.
> I often write the comment prior to the code, being a part of the
> structuring and modelling exercise.
Yup. That's the way it works. Otherwise commenting is a chore rather than an
ongoing conversation with the reader.
> 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.
That's an interesting idea. I think the principle distinction is between
"published" and "non-published", only the former implies any kind of contract
with the client code, or any constraint on future changes. I.e. not about who
is "allowed" to use methods, but about what guarantees are provided (and to
whom). But I like the idea of distinguishing the parts of the published API
that are central to using and understanding the module.
> 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.
In Dolphin that could be done quite naturally with method categories (since
Dolphin doesn't have the absurd restriction that a method can be in only one
category), which should be simple enough. Hmmm....
-- chris
| |
| Yanni Chiu 2006-03-02, 7:02 pm |
| Reinout Heeck wrote:
> My experience is that method comments are "invisible".
That is my experience as well - whatever the programming language.
However, if I print out the code (which sometimes happens in other
languages), then I might read the comments. But reading the comments
is the last thing I do to figure out how code works.
Chris Uppal wrote:
> For me the need starts /as/ I write the code. The comments are, amongst other
> things, my ongoing design notes.
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.
--
Yanni Chiu
| |
| Bruce Badger 2006-03-02, 7:02 pm |
| On Wed, 01 Mar 2006 07:37:26 -0500, Bob Nemec wrote:
>
> The rule that I follow is to comment intent, not action (the 'why', not the
> 'how').
Spot on, than man.
| |
|
| > 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.
None of these claims are persuasive and here's why not.
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.
M. Roberts
Cincom Systems, Inc.
| |
|
| > Architecture is communicated differently, mostly by pairing in our shop.
And that communication breaks down for the first developer who isn't
pairing with the guys who wrote the code.
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.
M
| |
| Yanni Chiu 2006-03-02, 9:57 pm |
| mdr wrote:
>
> And that communication breaks down for the first developer who isn't
> pairing with the guys who wrote the code.
>
> 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.
This is starting to sound like big-shop vs. small-shop
(i.e. big team, lots of teams, heavy weight process vs.
an agile shop).
Can we say that "code comments are required" is really
a local development process decision, not a universal
axiom of good coding.
| |
| Yanni Chiu 2006-03-02, 9:57 pm |
| So much to "comment" on. I'll just make a few.
mdr wrote:
> First, remember that Smalltalk has no concept of an interface and makes
> no distinction between public and private methods.
Aren't method categories sufficient. You would rather have
a method comment with "public" or "private", that you have
to select the method to see.
> Attention/focus are fundamental issues in the organization of a
> system and the design of its tools.
Right. And IMHO comments often just get in the way of reading the code.
When you look at a webpage, do you *see* the advertisements. I almost
never notice them; instead, the content (if any) is what I immediately
focus on. Wouldn't you rather see the webpage without the advertisements?
> Next, "if the code is not immediately clear" - for who? The
> implementor or the developers who want to use the code?
An implicit assumption seems to be that the code is being
delivered to developers in far away lands. For a Smalltalk
vendor, that might be true, and the cost of well documented
code needs to be factored in. For other cases, the cost of writing
and maintaining code comments needs to be weighed against the
potential benefits. Also needing consideraton are alternative
ways (and maybe more effective ways), other than code comments,
to transfer the knowledge.
> This is part of the reason that there are "code reviews" that
> involve several different people.
In the one case that I encountered a formal code review process that
involved several people, the overall project was a disaster.
> 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.
This statement I agree with, to some degree. But I thought someone
was advocating that simple accessor methods should be commented.
| |
|
| > Aren't method categories sufficient. You would rather have
> a method comment with "public" or "private", that you have
> to select the method to see.
Actually, I would like categories for this, but at present, they are
not used consistly and there is no agreed-upon convention. So, one must
look at the methods to see their comments or code and try and figure
out the API that way.
Bear in mind that I'm talking about some actual real live code that
exists, not a set of ideal rules that could be applied maybe possibly
hopefully someday in the future. I think it would be good to try and
figure out some better practices, but to my mind they also need to
account for code that already exists.
Arguably, there should be a convention for naming protocols, but there
isn't. We can say whatever we want here, but getting buy-in from a
development group or a vendor or a whole community is another matter.
And once we have that, the editorial job of going through hundreds or
perhaps thousands of classes to make the categories consistent will be
a big task.
The next problem is that categories don't capture anything more
detailed about the API, about what the methods do, so you still need
method comments for that. "Public/Private" is just one data point in an
API doc.
[color=darkred]
> Right. And IMHO comments often just get in the way of reading the code.
> When you look at a webpage, do you *see* the advertisements. I almost
> never notice them; instead, the content (if any) is what I immediately
> focus on. Wouldn't you rather see the webpage without the advertisements?
That's a flawed analogy. The advertisements on a web page are not
authored or maintained by the content author, they are not there to
help understand the article, and they generally have nothing to do with
the content.
> An implicit assumption seems to be that the code is being
> delivered to developers in far away lands.
Actually, I was thinking of two developers working in the same group of
the same company.
> For other cases, the cost of writing
> and maintaining code comments needs to be weighed against the
> potential benefits.
Well, here are some numbers for costs vs. benefits. I mentioned this
case elsewhere in the thread, but maybe you didn't read it.
Cincom acquired the Refactoring Browser and integrated it into
VisualWorks. It did not come with much in the way of code
documentation. Class comments were sparse or missing, APIs were not
clearly expressed using protocols and method comments. Later, we wanted
to build a CodeTool that would read the current state of the RB
navigator. I.e., you select a package, class, protocol, method,
browsing mode, etc., and another part of the tool receives this
information in a simple way. There was no clear API for the navigator
or the code tools, because the RB was developed XP-style. "But it's
simple, just go read the code." Right? In fact, there are inner
mechanisms which are non-obvious. A seasoned Smalltalk developer
working for Cincom spent 75 hours reverse-engineering that one
particular interface. Do the math: 75 hours of labor of an experienced
Smalltalk developer. Would it have really taken 75 hours for the
implementors to document the code to express the current selection in
the system browser? I really doubt it. Also, that was time spent just
to figure out how to use the RB code, not to write the missing
documentation. So, another developer waste more time "reading the code"
again next time.
> Also needing consideraton are alternative
> ways (and maybe more effective ways), other than code comments,
> to transfer the knowledge.
Can you be specific about "alternative" ways, and give some evidence in
support of any claims about "more effective"?
> In the one case that I encountered a formal code review process that
> involved several people, the overall project was a disaster.
At Cincom, our experience has been the opposite. Before, we had too
many problems during integration of unreviewed code. Now, the code is
written, reviewed, the reviewer signs off and then it gets integrated.
It's a lightweight review process and seems to serve us well.
> This statement I agree with, to some degree. But I thought someone
> was advocating that simple accessor methods should be commented.
That seems excessive.
M. Roberts
| |
| Yanni Chiu 2006-03-03, 3:59 am |
| mdr wrote:
>
> That's a flawed analogy. ...
It's a different expectation. I don't want to see code comments,
just like I don't want to see the advertisements. I start from
the assumption that the code will tell me what I need to know, and
comments, if present, may or may not be accurate.
> Well, here are some numbers for costs vs. benefits. I mentioned this
> case elsewhere in the thread, but maybe you didn't read it.
I think I saw it scoll by, back when I was trying to
avoid jumping into the thread. :-)
> Cincom acquired the Refactoring Browser ...
How could the RB authors know that Cincom would acquire the code?
Every moment spent writing code comments, is less time writing
code that does something, or refactoring the code for clarity.
Writing code comments are worth something too (75 hrs in your
example). In hindsight maybe you can see a potential saving,
if comments had been done earlier.
> Can you be specific about "alternative" ways, and give some evidence in
> support of any claims about "more effective"?
XP pair programming and developer room. Last year I landed
in a project with a six w deadline. I knew nothing at all
about the project, but I was paired with a guy who'd been on
the project 3 months earlier (but was sidelined due to the
company taking the project in-house). Over the course of the
six ws a lot of knowledge was transferred (not all, but lots).
As it happened, I continued on for six more ws, in the absence
of the first guy. And in my final w I paired with a permanent
team member who'd been present in the developer room throughout
(working on a related project). It was a fairly easy transfer
since he was already familiar with the business and the code.
Getting the knowledge into the right person's head,
and having a correcting working system was the ultimate goal.
The goal was not to have a well commented code artifact.
I doubt that we'd have got the system functionality done,
if we'd shifted effort into writing code comments. Despite
not writing lots of comments, there is still a knowledgeable
developer on the project.
Obviously, if you decimate or disperse the team, there will be a
restart price. But why follow a process that assumes your own
future demise, and therefore devote resources to code comments when
developers working side-by-side yields better communication.
> It's a lightweight review process and seems to serve us well.
Your original message said: "code reviews that involve several
different people". That did not give me the impression of a
lightweight process.
| |
|
| > I start from the assumption that the code will tell me what
> I need to know, and comments, if present, may or may
> not be accurate.
Indeed, and my point is just that if you translate that assumption into
a practice, you are passing extra costs on to other developers, because
you are requiring them to reverse-engineer code just to use it. And
those extra costs may make the difference been a development project
being reusable or not.
I'm not talking about verbose commentary sprinkled throughout a long
method, I'm talking about a method with one substantial comment at the
beginning, e.g., "Answers an OrderedCollection of strings or nil.
Throws a NotFound exception if foobar is empty."
I'm wondering if you're thinking of some other developer community that
is verbose with comments, and transposing your distaste for that onto
Smalltalk. Really, we don't write many comments in our code, trust me
;-).
> How could the RB authors know that Cincom would acquire the code?
This is a peculiar question. The RB authors have said, and I quote:
"The goal of our research is to move refactoring into the mainstream of
program development." There are different ways that might happen,
obviously, but they started their work in Smalltalk, they talk a lot
about "reusable software and frameworks", they developed a version for
VisualWorks, and Cincom is the largest Smalltalk vendor. They were
happy to work with us to help integrate it. Since then, we have found
the costs of maintaining the RB code to be much higher than
anticipated. Note that I have nothing against the authors' ideas about
refactoring. My concern is just with the *real* cost of maintaining and
reusing a framework that was developed without comments or API
documentation.
> Last year I landed in a project with a six w deadline.
It sounds like a constrained project plan pretty much forced you to
hunker down with your partner and do pedal-to-the-metal hacking. If the
goal was only to have a "correctly working system", okay. You suggest
that the goal *was not* to produce something that could be readily
reused by others outside of your group. So, you met the requirements.
However, for many projects, reuse is also a requirement, and for the
project you mention, it sounds like the information that would make
reuse possible without an unknown cost of reverse-engineering the code
(which introduces a large element of risk, of course) is in your and
your colleagues' heads. So, the effective reuse of the code depends
upon somebody else pairing with you. That may be fine in a small shop,
but if you are working in a large company with a dispersed team, or
working on a community project that is maintained in a public
repository, it begins to introduce costs that may be too high. My
colleagues are distributed in at least four different time zones.
> But why follow a process that assumes your own
> future demise, and therefore devote resources to code comments when
> developers working side-by-side yields better communication.
It's not about assuming your own demise, it's about assuming that the
audience for your project might be larger than just your small shop and
the one other guy you're pairing with.
Another way to think about this, I guess, is how large an audience you
want to reach. If you are comfortable or constrained to produce
something for a small audience, okay. Maybe there's no choice, or maybe
you don't care. I can't say. If it's a subsystem that is viewed as
disposible, if all that matters is that "it works correctly," okay.
Parenthetically, I don't really see that a methodology that relies on
direct one-on-one verbal communication is "better". I mean, sure, if I
call you on the phone right now and we have a conversation about this,
maybe it's "better" for the two of us, but if we have the conversation
here on c.l.s., suddenly it opens up the discussion to a much larger
audience, right? For that reason, I would rather talk with you here
than talk on the phone. Other people can get involved, etc. To my mind,
that's "better" communication because it involves more eyes and more
points of view. It's kind of funny, really, that we're talking about
this across the Internet, a huge mass communication medium that has
leveraged an explosion of sharing ideas and information, blah blah, and
what's apparently being advocated here is side-by-side unmediated
communication, a kind of return from writing and mass media to an oral
culture.
Having seen how code frameworks can become junk because nobody else can
readily understand them, I am more interested in development practices
that can produce code with a longer lifecycle. This is also something
that affects the learnability of a programming language, its growth,
its marketshare, etc.
Again, some of these methodologies may be fine for underbudgeted or
disposible projects, but if everyone in the Smalltalk community were to
never write another comment after midnight tonight, if we started
telling any noobs to get with the program and read our code, and if all
knowledge-transfer required pairing and side-by-side, direct
communication, I'll hazard that the community would stop growing, and
we'd begin to resemble a mystery cult.
The code produced by the Smalltalk cult would be very simple and
efficient, but nobody else would care.
M. Roberts
| |
| Ian Upright 2006-03-03, 3:59 am |
| "Bob Nemec" <bobn@rogers.com> wrote:
>
>The rule that I follow is to comment intent, not action (the 'why', not the
>'how').
>
>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.
>
>Bob Nemec
>Northwater Objects
Hi Bob,
I completely agree. Lets take the idea of documenting of an implementation
of a quad tree.
At a first glance, even with documentation and comments for each method, a
developer might not even have any idea of what the heck a quad tree is or
what it's purpose is. They might not have any idea of where is a good place
to use one and where is it not. They might not have any ideas of
alternative approaches. Perhaps they would like to see references to papers
or tutorials on the subject. This is all on the macroscopic level. Then on
the more microscopic level, presumably there have been a number of choices
made with regards to simplicity, performance, flexbility, etc.. Or perhaps
there is no reason for those choices at all, and the developer just doesn't
know or in the sake of saving time, doesn't immediately care, if it works
well enough to solve his problem.
So when we see a framework, we want to know many things:
1) what is it's purpose, and what are the potential use cases for it
2) what are the alternatives
3) what frameworks in the system depend on this framework
4) what are the pros and cons for the framework
5) what are possibilities for future direction or alternate approaches
6) at a more microscopic level, what are the approaches to the way it's
currently implemented, and how does each individual small peice work
Documentation at the method level is often the least of your problems!
Oh if only all our software was so well documented! I wish half the
Smalltalk I saw was documented even to the 10% level of this! The reality
is, that it's often not. Perhaps the developers are too ashamed that they
haven't really put that much thought into their frameworks, so giving an
explanation of it all isn't worthy, or it could be just down-right
embarassing. :-)
On the other hand, I'm a believer that if you actually forced developers to
write this sort of documentation, there might be a chance that the code is
half-ways reusable, efficient, and solves a real problem, as opposed to the
majority of one-off code that really should be destined for a trash can.
:-)
Ian
---
http://www.upright.net/ian/
| |
|
| > There was no clear API for the navigator
> or the code tools, because the RB was developed XP-style.
You seem to have a real aversion to XP - its not the first time I've noticed
cutting remarks...
XP done properly - does not lead to the kinds of flaws you describe in your
post - in fact, when I've seen it done properly it has a much more powerful
effect on code than simply writing comments.
Test first (done well) causes you to think about your relationships between
objects, and how you are going to show those objects working correctly. If
the tess are named correctly they also can give useful documentation. Refactoring
causes you to remove duplication, name things properly, simplify code...
etc. etc.
In my experience asking people to focus on those elements before they resort
to commenting has a much more profound impact on creating usable, easier
to maintain code. More often than not a comment is a crutch to other problems
- I always ask myself what I would do if I couldn't comment my code (name
variables and methods better, use longer names, extract long methods, simplify)?
Then I do those things, and then I look into whether a comment adds anything
additional. I am all in favor of class or package comments to give some context
(again - don't duplicate the obvious and if you can link some well known
doc's do that).
And by the way - pairing helps with the above immensely.
I think you unfairly target the RB codebase - it was done a long time ago
- XP was still in its infancy, the guys writing RB may not have have been
experienced in using XP ~(many of us were still learning back then) and would
probably do things differently now.
Having said this - Dolphin uses the RB stuff, and I found it quite easy to
pick up (maybe for IntelliDolphin I wasn't doing quite what you guys were
doing) but I got into its guts quite easily. I came away very impressed that
when I wanted to find out what keyword parameter was under my cursor, the
RB stuff implemented an #intersects: anInterval method on Nodes making this
trivial.
Tim
| |
| Ian Upright 2006-03-03, 3:59 am |
| "Chris Uppal" <chris.uppal@metagnostic.REMOVE-THIS.org> wrote:
[color=darkred]
>David Buck wrote:
>
Hi guys.. Well if you want to add some crazyness to it all, how about a
radically different view?
Why should we have a phoneNumber method in the first place? Maybe it should
be defined in some meta model as data and not in a method of Smalltalk code.
If you do so, then this concept is transferrable and available to other
programming languages, and tools. It's arguable that the concept of a phone
number doesn't belong in code at all. Then we take the step that perhaps
this metadata should have attributes on it like comments, perhaps it's
attatched to some webpage or other meta-data type characteristics. Perhaps
in english it's called phoneNumber and in a dozen other languages it's
called something else. Perhaps the metadata tools display this concept in
the language of choice instead of just english. Perhaps the metadata has
some constraints on it that declaratively indicate how this data is
formatted.
Then we just have frameworks that do everything else, and nowhere in our
code do we have the concept or even method of a phone number, because it
turns out we don't happen to actually need it. :-)
I'm playing devil's advocate a little bit here, but when it comes to
comments or even radically different software approaches, we all seem to
have our own opinion and perspectives as to what is right. Call it a
variety of religions if you like. :-)
Ian
---
http://www.upright.net/ian/
| |
| Andy Bower 2006-03-03, 3:59 am |
| MDR,
>
> Actually, I would like categories for this, but at present, they are
> not used consistly and there is no agreed-upon convention. So, one
> must look at the methods to see their comments or code and try and
> figure out the API that way.
Hmm... I think what you mean here is that VisualWorks doesn't have any
support for multiple categories which would be a prerequisite for using
them for flagging methods as public/private etc. I agree with you that
public and private flags are an essential part of the "documentation"
but I don't agree with you that they should be included inside method
comments (unless, as is the case with VW, you currently have no
alternative). I think the correct solution would have been to fix
VisualWorks' categories so they were more useful.
> Arguably, there should be a convention for naming protocols, but there
> isn't. We can say whatever we want here, but getting buy-in from a
> development group or a vendor or a whole community is another matter.
> And once we have that, the editorial job of going through hundreds or
> perhaps thousands of classes to make the categories consistent will be
> a big task.
Personally, I think it is a larger editorial job to go through
thousands of methods giving them all method comments especially when
these comments will eventually go "stale". At lease category/protocol
information will be maintained by the system during refactoring
operations etc. so it has a very good chance of reflecting the actual
code in five years time.
>
> That seems excessive.
I thought you said that methods should at least be flagged as being
public or private in the comment. The convention is, of course, to mark
only private methods. Since there are generally more private methods
than public surely this will mean that a lot of simple accessor methods
will end up being commented.
Best Regards
--
Andy Bower
www.object-arts.com
| |
| Yann Monclair 2006-03-03, 7:57 am |
| I am but a student, and have little experience with big projects. But
from my experience, when I was brought to reuse code, I like to mess
around with the example methods. create an instance, browse through it,
see the different messages it can handle ... I discover the code
through the inspector and the example methods.
I also like to read a documentation on the aim of the project. I have
worked mostly on research projects, and reading about the scientific
context, the technological context, the ideas used in the project, is ,
imho, more useful to grasp the intent of the project, than comments on
this or that method. comments on a method also assume you will browse
through the methods, why should one have to browse a
method/class/parcel he is just using, not editing. I think (hope) you
can avoid that.
Code commenting is not -imo- replacing documentation. They have to be
distinct, because there is a huge difference between the developer that
has to use your code/framework and the developer that has to modify it.
They don't need the same information on the code, the intent, the means
used.
Yann
| |
|
| > I think you unfairly target the RB codebase - it was done a long time ago
> - XP was still in its infancy, the guys writing RB may not have have been
> experienced in using XP ~(many of us were still learning back then) and would
> probably do things differently now.
The authors of the RB will have to answer this question themselves, but
the paper they published in "Theory and Practice of Object Systems"
states: "In fact, we regularly use the Refactoring Browser on itself."
M
| |
| Andy Bower 2006-03-03, 7:57 am |
| MDR,
> Cincom acquired the Refactoring Browser and integrated it into
> VisualWorks. It did not come with much in the way of code
> documentation. Class comments were sparse or missing, APIs were not
> clearly expressed using protocols and method comments. Later, we
> wanted to build a CodeTool that would read the current state of the RB
> navigator. I.e., you select a package, class, protocol, method,
> browsing mode, etc., and another part of the tool receives this
> information in a simple way. There was no clear API for the navigator
> or the code tools, because the RB was developed XP-style. "But it's
> simple, just go read the code." Right? In fact, there are inner
> mechanisms which are non-obvious. A seasoned Smalltalk developer
> working for Cincom spent 75 hours reverse-engineering that one
> particular interface. Do the math: 75 hours of labor of an experienced
> Smalltalk developer. Would it have really taken 75 hours for the
> implementors to document the code to express the current selection in
> the system browser? I really doubt it. Also, that was time spent just
> to figure out how to use the RB code, not to write the missing
> documentation. So, another developer waste more time "reading the
> code" again next time.
I had been hoping to avoid jumping into this thread since it is a
perennial topic and rarely produces any general consensus at the end.
However, I can't let the above pass.
Our first experience of XP was in porting the Refactoring Browser to
Dolphin back at the first Camp Smalltalk in 2000. As you know, the RB
is a fairly large chunk of code and yet, even though there are
virtually no unnecessary method comments in the code it is was
documented by means of the supplied tests. This was so effective that
we were able to port the entire RB engine (sans GUI) to Dolphin
Smalltalk within five days and this was without knowing anything about
how it worked or, indeed, much about what Refactoring actually was (I
think we'd seen John and Don's VisualAge demo, that's all).
This w was a revelation to me since it showed that test first design
could have a *real* impact on how maintainable a framework or
application was into the future even by people with no experience of
the original development. We have since gone on to integrate the RB
fully into Dolphin Smalltalk without having to spend hundreds of hours
reverse engineering the RB codeBase in the way you suggest stop.
In my experience there are a lot of people (even seasoned Smalltalkers)
who don't accept that the code in the image is the best source of
"documentation" you can have. By this I don't mean that it is
*necessarily* the only sort of documentation that should be present but
it is, by its very nature, entirely accurate and entirely maintenance
free. When good intention revealing Smalltalk code is modified, the
descriptive information that it contains is carried with it.
In general, I am sometimes in favour of class comments which provide an
overview of the relationships between various classes or subsystems.
However, even these are generally better expressed as high-level tests
which, if appropriately named, can illustrate usage scenarios for
complex frameworks. As an example, the Object Arts website uses Swazoo
and I don't remember having to read a single class comment while trying
to figure out how to use it. I believe there maybe some comments in the
Swazoo codebase but I really don't know because it was never necessary
to look at them.
(to be fair, there was or one area in Swazoo where we had to ask for
some outside help but that was because no appropriate usage tests had
been written)
>
> Can you be specific about "alternative" ways, and give some evidence
> in support of any claims about "more effective"?
In a few places in this thread you have suggested that the burden of
documentation is being deferred onto the framework users by people who
attempt to use intention revealing code as their only means of
documentation. You suggest that code often needs "reverse engineering"
to find out what it is doing.
However, I would not see it like this. I would suggest that any code
certainly needs "parsing" by the human brain in order that the
programmer can glean what it is saying. However, plain text comments
also need parsing. Smalltalk methods should be written, wherever
possible, so that they can be parsed at a glance in at least as short a
time as a natural language comment.
Best regards,
--
Andy Bower
www.object-arts.com
| |
|
| > I agree with you that public and private flags are an
> essential part of the "documentation" but I don't agree
> with you that they should be included inside method
> comments [...]
I'm not saying public/private should be indicated in the method
comments. Somebody else (Mr. Chiu, perhaps) is inferring that.
My point is that the Smalltalk *language* doesn't offer much help here
and in lieu of a generally agreed-upon convention, the public/private
distinction has been expressed in different ways by different vendors,
even within a single vendor's class library, and that often it is
necessary to look at comments or code to figure it out.
I agree with you that categories in VisualWorks are not up to the task,
and need to be improved somehow. Multiple categories would be a good
solution. A public/private flag is another solution (for simplicity,
the one implemented in SmalltalkDoc).
How does Dolphin handle this?
Beyond this, there are other requirements for API documentation. Just
being able to distinguish public from private is not enough. the
problem here is that if the "best practice" is that it's OK to
reverse-engineer code, omitting comments and telling everybody that
they should just be reading code, it's not possible to have API
documentation. Nobody will write it.
[=2E..]
> I thought you said that methods should at least be
> flagged as being public or private in the comment.
No, see above.
To summarize a bit: the Smalltalk language doesn't provide some of the
basic information needed to express the public interface of a class.
Some implementations (e.g., Dolphin) may have corrected this by adding
multiple categories, but some (e.g. VisualWorks) have not. IMHO, the
deficient implementations should be fixed and, ideally, some kind of
vaguely similar convention might be followed by more of the vendors (if
Dolphin has a good solution, perhaps that could be the model). The
public/private information, along with a concise, but expressive
comment that describes the behavior of a public method (e.g., return
values, exceptions, might return nil, etc.), is needed to produce API
documentation.
What concerns me in this whole discussion is the tendency to say that
as a matter of general practice it's OK to forgo comments, that
developers should always be reverse-engineering code ("because comments
lie"), that Smalltalk IDEs don't need any better facility to express an
API than what currently exists in, say, VisualWorks, and that while the
rest of the industry recognizes the critical importance of API
documentation, for some reason perhaps having to do with XP,
Smalltalkers don't need API docs, and should always be reading code
(and if you don't comment your code, you're basically saying that
anybody else who wants to use it has to reverse-engineer it).
I submit that when developers assume that others *should* be reading
code, there is an impact on use, reuse, approachability,
documentability, learnability, and productivity of application
developers.
As an alternative, I would like to suggest that Smalltalk developers
simply acknowledge the value of comments and especially API docs, and
that developers who have any aspiration to publish or share their code
should seriously consider comments and documentation as part of the
development process. This doesn't mean slavishly commenting every
accessor method or incremental updates for every change in a method
(many can wait until they have been refactored and published as a
release of some sort).
As I've said before, I think some of this can be automated. The impact
on developers does not have to be great. The generation of API docs,
for example, could and probably should be automated (=E0 la
SmalltalkDoc), but some information has to be in place to make this
possible.
M=2E Roberts
| |
| David Buck 2006-03-03, 7:57 am |
| mdr wrote:
> Cincom acquired the Refactoring Browser and integrated it into
> VisualWorks. It did not come with much in the way of code
> documentation. Class comments were sparse or missing, APIs were not
> clearly expressed using protocols and method comments.
In order to transfer control of code from one person to another, it
helps tremendously to have good documentation. The documentation should
be structured in a way that a person who has never seen this code can be
introduced to it in a logical sequence.
The best documentation starts at the beginning, introduces the problem,
shows the high level architecture of the solution, drills down into
individual areas giving examples about how they work, and describes the
classes that are involved along the way. It describes a system that
exists not a system that the developers plan to build. This kind of
documentation tends to be fairly resiliant in the face of changes.
This would clearly have been helpful in the case you mentioned above. In
the absence of this kind of documentation, you have to take what you can
get. Class comments are good but there's no nice way to order them to
guide a new developer through the system. Reading class comments in
alphabetical order is usually the wrong order.
Method comments don't give you the big picture which is really what you
need. Reading method comments, you'll have a hard time seeing the forest
for the trees. If the method comments just re-iterate what the code
says, then they're useless.
Method comments are good at documenting:
- method-level algorithms - ("From Numerical Recipies page xxx")
- intent that's not clear from the code
- complicated code that's not well factored
(my definition of complicated is very strict)
- tricky bits
("clear this variable now so the next call creates a new instance")
If you can refactor your code to eliminate complicated code and tricky
bits and the code nicely expresses the intent, then you don't need the
comment. If you don't refactor (or choose to postpone it), by all
means, comment it.
David Buck
Simberon Inc.
www.simberon.com
| |
|
| Andy,
Thanks for recounting your experience (though you had the urge not to).
A few thoughts:
I have no issue with TDD, I use it myself, and I agree with you that it
really helps make a framework more maintainable.
W.r.t. the experience of integrating the RB code base:
Cincom did this as well, the RB code base is now the System Browser in
VisualWorks. We spent a lot of time tweaking the UI (the original RB UI
needed much work), so I can't say how long that took. But I am not
comparing the experience of porting the code base (and, if you please,
don't unfairly gloss what I said: "75 hours" is not "hundreds of
hours"). Much of that work was done by the RB authors before we even
started. Rather, I am speaking about adding new functionality to the
RB, i.e., trying to use an API inside the RB (CodeTool) to extend its
functionality in a standard way (i.e., we were not trying to make it do
something it wasn't designed to do), and that's where we ran into
trouble. That is, it wasn't a matter of just taking a black box (RB)
and making it work in our IDE, but actually extending it in some
interesting way. That's when the lack of documentation tripped us up.
> In my experience there are a lot of people (even seasoned Smalltalkers)
> who don't accept that the code in the image is the best source of
> "documentation" you can have. By this I don't mean that it is
> *necessarily* the only sort of documentation that should be present but
> it is, by its very nature, entirely accurate and entirely maintenance
> free. When good intention revealing Smalltalk code is modified, the
> descriptive information that it contains is carried with it.
Theoretically, sure. Code is code. By nature it is what it is. But
that's not the issue. The issue, as you emphasize, is the "necessarily"
part. That's the slippery part.
I don't see that pointing out that code = code is something that we
could really turn into a development practice, it's certainly not
something to say to noobs. I.e., "Yes, we know you are all used to
comments and API docs in every other IDE, but believe us, you don't
need that stuff. Our undocumented code is by its nature a more accurate
source of documentation that all of those books you can find on other
languages. It make take you a few hours to figure out that method in
class Dictionary, but you'll get the Truth."
> In general, I am sometimes in favour of class comments which provide an
> overview of the relationships between various classes or subsystems.
> However, even these are generally better expressed as high-level tests
> which, if appropriately named, can illustrate usage scenarios for
> complex frameworks.
I don't know about Dolphin, but in VisualWorks, class comments often
have examples of use. These are very efficient for showing use. In
contrasting the simplicity of example code in class comments with unit
tests for complex frameworks, I am leery of the creeping complexity, of
generalizing a case that handles complexity and trying to say that it
is suitable for simple cases, too.
Reading tests is like reading code. A pile of test classes with
hundreds or thousands of test methods - where do I begin? There is
much more effort involved. I don't see that these are an adequate
substitute for class comments or API docs. Supplement, sure.
Substitute, no. Really, I want both. But to say that tests are
"better"? What do you mean by "better"?
Does "bettter" mean "more true"? There are a lot of times when this
doesn't matter.
If I just want to figure out how to use some web services, isn't it
easier and more efficient to have a decent class comment or API doc?
For example, I just want to open up an HTTP stream and get a document
from some server.
Either I can (a) read the class comment and get some example code that
I evaluate with doIt, or (b) go off and find the tests... i.e., "oh
right, of course they're not in the base image, got to load them from
the repository, let's see, which version are we talking about here?
Let's go back to the browser. OK, got it. Tests are loaded. Now, how
are these two hundred classes organized? (Later) OK, got it. OK, let's
start clicking on "senders" to get the tests that best illustrate usage
scenarios for class HTTP. Hmm, a dozen methods. I wonder which one I
should start with? Nope, not that one. OK, let's see, what's going on
in this method. Looks like a bunch of initialization, okay, setting up
a bogus document, okay, etc. etc. etc."
> I would suggest that any code certainly needs "parsing" by the human
> brain in order that the programmer can glean what it is saying. However,
> plain text comments also need parsing. Smalltalk methods should be
> written, wherever possible, so that they can be parsed at a glance in at
> least as short a time as a natural language comment.
"Should be written...". Sure. This is fine as a general rule, as an
ideal, but in practice we encounter code all the time that wasn't
written like that. What then? What about an existing subsystem? Rewrite
it? OK, where's the budget? What about the base Smalltalk class
library? Most of it was written before the Smalltalk community started
talking about this idea of methods that read as easily as English. As
you point out, it's "wherever possible".
Regards,
M. Roberts
| |
| Bob Nemec 2006-03-03, 7:57 am |
| "Ian Upright" <ian-news@upright.net> wrote in message
news:kguf02h0njqom2k6lv3biror4b3d8kfjdb@
4ax.com...
<...>
> Oh if only all our software was so well documented! I wish half the
> Smalltalk I saw was documented even to the 10% level of this! The reality
> is, that it's often not.
<...>
Since we're on the topic, I'd like to point out that Eric Clayberg's
comments and categorization of methods in VA WindowBuilder and widget kits
is first rate. I've been using the tools for years now, and I've almost
always been able to figure out how get things done on my own.
Eric puts the most useful public methods in an API suffixed category (VA
allows for multiple categories per method). It's a great way to start
figuring out what behaviour a widget provides. And even the private methods
are well commenting, making it much easier to do the quirky stuff.
So yes, most Smalltalk code is not well documented... but some is.
Bob Nemec
Northwater Objects
| |
| Chris Uppal 2006-03-03, 7:57 am |
| Ian Upright wrote:
> On the other hand, I'm a believer that if you actually forced developers
> to write this sort of documentation, there might be a chance that the
> code is half-ways reusable, efficient, and solves a real problem, as
> opposed to the majority of one-off code that really should be destined
> for a trash can. :-)
I know that it has quite often happened to me that when I'm writing external
documentation for something, I'll find that I'm explaining an unexpected
restriction or inconsistency, and think "why am I writing all this waffle?",
and go back and fix the code. Thus shortening the documentation.
I.e. I concur.
-- chris
| |
| Chris Uppal 2006-03-03, 7:57 am |
| Yanni Chiu wrote:
> An implicit assumption seems to be that the code is being
> delivered to developers in far away lands.
Actually, the assumption is /explicit/ ;-)
> This statement I agree with, to some degree. But I thought someone
> was advocating that simple accessor methods should be commented.
That was probably me. I'll explain -- or try to.
First off, I don't believe that in well-written code there is any such thing as
an accessor. There may be many methods with the /form/ of an accessor, but
their purpose is not:
Answer the value of the xxxx instvar.
But:
Answer <some significant info about this object>
Now, whether the implementation is long and complicated, or is as simple as:
^ xxxxCache.
is not relevant to the caller of the method, nor to the person who is
attempting to understand the code. Hence the burden of responsibility (heavy,
light, or zero according to how you see things) for producing understandable
method comments is just the same for long methods as for short. True, the
complicated method will almost certainly require internal commentary, whereas
the simple one will almost certainly not. But that has nothing to do with the
method comment. (Although I admit that I often am sloppy about separating the
two in my own code).
From the POV of the person writing the method there is much that is totally
obvious, which is /not/ obvious to the person attempting to use that code.
Which is what my #phoneNumber example was intended to try to illustrate.
I repeat my earlier assertion: developers who think their code is too clear to
need comments are (in my experience) /always/ wrong. (I think that applies in
small closed shops too, but that's not the subject of this thread, and I'm only
talking here about "open" code).
-- chris
| |
| Chris Uppal 2006-03-03, 7:57 am |
| Yanni Chiu wrote:
> This is starting to sound like big-shop vs. small-shop
> (i.e. big team, lots of teams, heavy weight process vs.
> an agile shop).
Recall that this thread started with a plea/observation/grumble about the
quality of commentary in code that /was specifically intended for use in other
places/. I.e. third party libraries, and vendor-supplied code.
Whether there are ever any good reasons for a comment-free style for use in a
restricted context is a completely dfifferent question, and not at all relevant
here. (Unless you take the topic of the thread to have drifted).
All I can say is that when /I/ find myself working with code produced by
someone in the anti-comment camp, then it's much harder for me to use that
code. It's harder still if I have to modify or extend it. I /simply don't
care/ whether the person who produced that code thinks that comments are a
waste of time. The lack of them wastes /my/ time.
-- chris
| |
| Chris Uppal 2006-03-03, 7:57 am |
| Ian Upright wrote:
> Then we
> take the step that perhaps this metadata should have attributes on it
> like comments, perhaps it's attatched to some webpage or other meta-data
> type characteristics.
Then we'd have exactly the same problem with meta-engineers who believe that
commenting the meta-data is a waste of time, and that good meta-models are
entirely self documenting, and who routinely ignore or even remove any comments
that have been added.
Ever seen a DTD that was written without the assumption that the reader
was both a domain expert /and/ telepathic ?
;-)
-- chris
| |
|
| Yanni Chiu wrote:
> Can we say that "code comments are required" is really
> a local development process decision, not a universal
> axiom of good coding.
Yes, if the "local development" means really local, i.e no general use.
Let me explain: I have been working for a long time the technical
support. So perhaps I have a special POV.
Have you tried to give answer to a customer question (or solve a
customer problems) about a product based on an uncommented, maybe with
the best Xp style developed unknown code in the absence of of the
original developers?
My experience shows you have either no chance, or it can take days,
ws, sometimes months... (and the customers need the fix of course
yesterday.)
And even worse if you have to find why the code does not that what the
original developers intended. "It should work that way". Yes, but it
does not in some cases, what the customers unfortunately have found,
and the pair programmers have not even thought about.
I have the experience that the customers are very clever, and they find
and try all impossible situations about which the original developers
did not even dream, that it was possible. So checking the testcases is
useless, because they do not cover this special situation.
And if you do not have any information about what the pair programmers
originally intended at some point of time in the past... then you are
simply lost.
Here every small piece of information is very helpful, so the comments
have immense value, and can reduce the response time spent mostly on
detective work to catch an unknown killer.
It is interesting: as a developer I use the code differently (many
times I do not have to understand really what the code does. It is
enough to say: well, yeah, this makes sense, this too. Let's see if it
it works this way. let's try that...), so in the "developer" role I am
not in the big necessity of informative comments, although they are
useful, and help.
But in the support you are simply lost without them.
So if your intention is really write a code which is intended to be
used by others, the helping docs, and commentaries are a must (for the
others, who try to use your code). If you write the code for youself,
then of course you do not have to help yourself.
But maybe it is a too special point of view.
Best regards,
Janos
| |
| Andreas Wacknitz 2006-03-04, 6:59 pm |
| My experience is that people who aren't willing to write method comments are
aren't willing
to write class comments for mostly the same reasons (not necessary because
the code and tests
are self commenting). Further, most of them aren't able to write decent
documentation or specifications.
Furthermore, those form roughly the same group that is neither able to read
documentation nor specifications.
Maybe they have a different way of comprehension.
Andreas
| |
| Yanni Chiu 2006-03-04, 6:59 pm |
| Andreas Wacknitz wrote:
> My experience is that people who aren't willing to write method comments are
> aren't willing
> to write class comments for mostly the same reasons (not necessary because
> the code and tests
> are self commenting). Further, most of them aren't able to write decent
> documentation or specifications.
> Furthermore, those form roughly the same group that is neither able to read
> documentation nor specifications.
Sigh. Why is it that most of those arguing for method comments
like to portray as lesser or lazy programmers, those that argue
against lots of comments.
Writing good documentation takes time. Method comments are not
a substitute for good documentation and specifications. If those
docs are required then account for it and get the right people
the write them. Writing prose, quickly and clearly, is not a
skill all developers necessarily possess. Wouldn't it be more
effective and efficient to have developers stick to coding -
spending their time refactoring, choosing good method and variable
names and writing test cases - rather than writing prose in comments.
It's sound engineering tradeoff to not spend effort, unless
absolutely necessary. Each team needs to determine that tradeoff
in their particular case.
> Maybe they have a different way of comprehension.
Yes, they look first at the code. With refactoring and good
method/variable names that's usually sufficient. When it's not,
is the correct solution to have a method comment? Can a simple
method comment fill in for whatever gap in understanding exists
at that moment? In some cases, yes (for example, the YYY algorithm
is used ...). But does that translate to: good code has comments,
and uncommented code is bad?
| |
| Andreas Wacknitz 2006-03-04, 6:59 pm |
|
"Yanni Chiu" <yanni-REMOVETHIS@rogers.com> schrieb im Newsbeitrag
news:7dydnbE0AshDVpTZRVn-ug@totallyobjects.com...
> Andreas Wacknitz wrote:
>
> Sigh. Why is it that most of those arguing for method comments
> like to portray as lesser or lazy programmers, those that argue
> against lots of comments.
Re-sigh. Why do most lazy people claim that comments are unnecessary
and documentation should be written by others?
>
> Writing good documentation takes time. Method comments are not
> a substitute for good documentation and specifications. If those
I fully agree with you here.
> docs are required then account for it and get the right people
> the write them. Writing prose, quickly and clearly, is not a
Novelists usually don't make good writers for software documentation.
> skill all developers necessarily possess. Wouldn't it be more
> effective and efficient to have developers stick to coding -
> spending their time refactoring, choosing good method and variable
> names and writing test cases - rather than writing prose in comments.
I call those poeple hackers not software developers.
Developers need to communicate - and writing documents is just one
kind of communication.
>
> It's sound engineering tradeoff to not spend effort, unless
> absolutely necessary. Each team needs to determine that tradeoff
> in their particular case.
>
>
> Yes, they look first at the code. With refactoring and good
> method/variable names that's usually sufficient. When it's not,
> is the correct solution to have a method comment? Can a simple
> method comment fill in for whatever gap in understanding exists
> at that moment? In some cases, yes (for example, the YYY algorithm
> is used ...). But does that translate to: good code has comments,
> and uncommented code is bad?
I would rather say undocumented code is bad.
| |
| Vassili Bykov 2006-03-04, 6:59 pm |
| "Why waste money on a handicapped ramp; I have no problem climbing those
stairs."
(from another, imaginary, conversation on the subject of alternative access)
I found out about this thread just as I was wishing for a comment in a
large body of very uncommented very XP code (thank you Bob), so I
couldn't resist a somewhat incensed post on my blog. I'm not copying it
here (the URL is in the .sig) but here is how I see the main contention
point.
It's whether redundant information is good. The anti-comment camp argues
that comments are useless because they are redundant. And I suspect some
in that camp sneaked in because they believe work is redundant.
Evolution seems to be quite fond of redundancy. Human perception uses it
to restore the message when one channel becomes garbled. For example: we
can raed txet srcelmbad so taht olny the fsirt and the lsat lteetr of
ecah wrod are in palce.
Comments are that alternative channel. Yes they are redundant. Yes they
need extra work to maintain. Yes when you don't need them you don't even
see them. On many of your car trips you don't need the seatbelt either.
As I argued in the other post, this is a UI issue. The anti-comment camp
is approaching it from the wrong side, just as a typical software
engineer approaches UI design from the wrong side. It's not about "it
works and it's right, therefore it's possible to understand and
everything else is redundant". There is a usability gap between
"possible" and "easy".
You can't predict the future minds of your readers to know from what
perspective they will approach your code. If they are not sitting next
to you, a comment is the only backup channel for when your code stutters
at revealing its intention. Of course, you can't predict all that when
you are writing a comment either, but at least you are trying. And,
writing _good_ comments which augment rather than just repeat what the
code says is a skill not everyone has--or cares to acquire. Especially
when there is such a  excuse not to try.
Incidentally, regarding the XP angle--in my "journalistic research" for
the other post I was amazed to discover that comment extermination is
nowhere to be seen in language-agnostic XP documentation on the web.
Could the association between XP and anti-comment stance so popular
among Smalltalker be an atavism of 10-year-old propaganda, when everyone
else has since matured and found a middle way?
Look, here is a quote from "Sams Teach Yourself Extreme Programming in
24 Hours", Chapter 6, "Extreme Programming Practices in Action" (how
much more mainstream can you get?
http://www.informit.com/articles/ar...&seqNum=13&rl=1)
"Comments are an English description in the code that explains the logic
of the code. (Quality code should be self-documenting by default.) The
use of quality commenting gives quality code better maintainability and
easier understandability."
Is it time for XP/Smalltalk to grow up too?
--
Vassili Bykov
v b y k o v A T c i n c o m D O T c o m
http://www.cincomsmalltalk.com/userblogs/vbykov
[:s | s, s printString] value: '[s: | s, s printString] value: '
| |
| Yanni Chiu 2006-03-04, 6:59 pm |
| Andreas Wacknitz wrote:
>
> Re-sigh. Why do most lazy people claim that comments are unnecessary
> and documentation should be written by others?
Your reply just re-inforces my point.
BTW, I don't claim comments are unnecessary, only that comments on
every method are unnecessary and that comments are not always the
best way to communicate.
Also, documentation should be written efficiently, and programmers
are not necessarily efficient or capable writers of documentation.
Do you think every programmer could and should be able to write
a how-to book about some system they're working on? Some can and do,
and many could probably write it, but it might take a long time.
That's not an efficient way to get documentation written.
However, writing clear and concise code comments, when necessary,
is definitely a required skill. The "when necessary" is the question.
If the programmer can structure the code such that comments then
appear to be unnecessary, then I see nothing wrong with that.
>
> Novelists usually don't make good writers for software documentation.
Prose is not fiction. From dictionary.com:
"Ordinary speech or writing, without metrical structure"
I mean prose, as in what is written in code comments, as contrasted
with the actual code written in a formal programming language.
> I call those poeple hackers not software developers.
You are entitled to your opinion.
> Developers need to communicate - and writing documents is just one
> kind of communication.
That is my point too. And that, code comments is one of many
ways to communicate. But you cannot conclude from that that
code without comments is bad code, and programmers who don't
comment their code are lazy and stupid.
Someone earlier in the thread remarked that this subject erupts
now and than, with no useful result. I've been reading a book
that I happened across about the "Fifth Discipline" - a management
"fad" about engendering a "learning organization". From what I
understand so far, people have fundamental goals and values
which drive their perceptions and responses. Unless people's goals
and values are somewhat aligned, effective communication cannot
occur, because they'll just take past each other.
With this perspective in mind, I think I understand why every
argument made against requiring code comments is meant with a
fierce response. When I suggest that comments are an option which
should be weighed along with everything else, to determine
whether the effort should be expended, I have then run straight
up against a core value of "code must have comments".
Is is possible to align ourselves by focusing on fundamental
goals such as the need for communication and the need to make
tradeoffs to work within the constraints of a real project.
| |
| Yanni Chiu 2006-03-04, 9:56 pm |
| Vassili Bykov wrote:
> I found out about this thread just as I was wishing for a comment in a
> large body of very uncommented very XP code (thank you Bob), so I
Didn't you actually want the gap in knowledge you had at that
point filled in? If there had been an overview document that
provided sufficient context that the problematic method you
encountered was immediately clear from reading the code, or if
Bob was just a phone call away, then your knowledge gap would
still have been filled. As you point out, redundancy is good.
But, the world provides it in many ways, not just code comments.
> It's whether redundant information is good. The anti-comment camp argues
> that comments are useless because they are redundant.
Redundancy costs. Do you see nuclear reactors with extra reaction
vessels? Other parts of the reactor may have redundancy, but someone
has made tradeoffs based on costs and risks.
> And I suspect some
> in that camp sneaked in because they believe work is redundant. | | |