Gabriel Sechan wrote:
From: Christopher Smith <[EMAIL PROTECTED]>
Yeah, Smalltalk folks in general tend to frown on comments. They see
it as a sign that a method is complex. Complexity is sometimes
warranted (in which case comments are insisted upon, rather than
frowned upon), but most often not. The preferred approach is to have
short methods with descriptive names (this is helped tremendously by
the way Smalltalk method names work when you have multiple parameters).
Meaningful names are good, but nowhere near sufficient. They don't
tell us what assumtions have been made, valid input ranges (if not the
entire range of the type), or why you're doing what you're doing
(general rule of comments- why, not how, unless the how is really
complex). The two aren't exclusive, they complement each other.
I did mispeak. The kind of comments I was referring to were the "and now
we do this" kind of comments. Things like what you are talking about
tended to get documented either at the top of the method or, more often
in the class or the category of the method. Occasionally the "why"
question does need to be commented in a method, and that's definitely
not a sign of complexity, although it can be a sign of fragility.
In general though, with dynamically typed languages like Smalltalk, you
make *very* few assumptions and the notion of "valid" input ranges tends
to also be quite uncommon (mostly applies to your models where you are
enforcing business rules). You name your parameters after the protocol
you expect them to implement, the large Smalltalk library already
provides you with clear contracts for a lot of common protocols, and in
your typical method you might only invoke 1-3 methods from that
protocol. Just not a lot there to comment on. Now, for the category or
the class there often are some more specific assumptions.
Don't forget documentation. People think that XP says not to do
documentation, but it doesn't. It says to push off writing any
documentation until it's going to be used or the end of the project,
whichever comes first. The idea behind this is that the projects, the
code, etc. change over time and you end up with all this
"documentation" which is inaccurate the first time it is actually
used (raise your hand if you've not experienced this phenomenon
before ;-) or worse still you spend all this time refactoring
documentation to keep it up to date.
There's a multitude of problems with this
1)No manager in the world is going to let you sit around documeenting
for a month instead of doing "real work".
This would seem to be a problem with doing documentation period, whether
with XP or not.
2)People leave- they won't be around to document at the end
One of the key aspects of XP is that the "bus count" is kept high
(partly from paired programming, partly from shared code ownership, and
partly from aggressive use of unit tests), so people leaving tends not
to cause knowledge to disappear from the team.
That said, when someone is leaving the team you invariably identify that
this is a point where getting some documentation from them would be
useful (unless they are fired on the spot, usually you don't like them
coding/debugging/whatever up to the moment they leave, so documentation
is a fruitful use of their time).
3)People get added- there's no documentation to bring them up to speed
This is definitely a case where some documentation would in fact be
used, so writing up documentation for folks getting added to the team to
read is entirely within XP practices, and in fact encouraged (certainly
I've not joined an XP project that didn't have a day's worth of docs for
me to read, and unlike a lot of projects, they actually were as up to
date as the last iteration).
XP also partially addresses this problem with paired programming.
Typically what you see happening is one guy watching someone code for a
bit and then spending a lot of time in the drivers seat with the coach
guiding them through what they are doing until they get a grasp for the
system.
4)XP projects are about rapid iterations- they never really end, so
you'd never get around to documenting
Ah, so you never get in to maintenance mode? ;-)
XP projects definitely have rapid iterations, that doesn't mean that
eventually the iterations won't come to an end. Unless someone on the
business side keeps throwing in new things in to the to do list, you
should eventually run out of items to do.
5)People forget- half the reason for docs is to remind the
programmers of the design and implementation they're writing. No
docs, nothing to go back to when you're forgetting details
Again, XP is *not* about no docs. If you are going to need the docs, by
all means you write things down. Admittedly people can be optimistic
about what they think they can remember, but most programmers I know
tend to assume the worst because we tend to be forgetful people and
they've been burned before.
Not to mention the pure inanity of it- you're supposed to rapidly
refactor code, but for documentation its suddenly bad?
Part of the deal with rapidly refactoring is that you want to cut out
anything unnecessary from the refactoring process that slows it down. If
each refactoring requires a design committee meeting, a code review
meeting, several meetings with a tech writer, a meeting with the QA
team, etc., pretty soon your refactoring stops being "rapid". So, one of
the things to do is get rid of all the documentation that is written for
no other purpose than to check mark something in a process book as being
done. If you write a doc and nobody reads it for reasons other than
verifying that you wrote the doc, chances are that was a doc that didn't
need to be written until later (or never).
Yeah, you need to go back and tweak it every so often. No big
deal. At least you have it to go back to. THe idea of no design (or
"the tests are the design", which is the same thing), no
documentation, no comments are all signs of a lack of professionalism,
a lack understanding of software engineering and quality, and a lack
of respect for your coworkers and those who will maintain the
software. If I had someone on my team who took any of those stances,
I'd do my damndest to get him fired, he's a liability to the team.
To clarify here:
1) I think you've misinterpreted the "tests are the design" statement.
XP doesn't advocate no design (although I've seen people abuse it this
way). Indeed, it argues for continuous design. You never really stop.
Writing tests first helps a lot with the design process (try it, it
really helps), and that is what that quote refers too.
2) You've definitely misinterpreted the "no documentation" bit.
3) While some comments are necessary, clear and simple code with good
unit tests goes a long way to reducing the need for them, and having
clear and simple code with good unit tests is far kinder to your
coworkers than having muddled, complex code with no unit tests. So while
never commenting your code is a bad idea, it is a good idea to think,
"is there a way to do this such that this comment I'm about to write
would be superfluous?"
--Chris
--
[email protected]
http://www.kernel-panic.org/cgi-bin/mailman/listinfo/kplug-lpsg
