|
This page contains an archived post to the Design Forum made prior to February 25, 2002.
If you wish to participate in discussions, please visit the new
Artima Forums.
Message:
Because ... documentation is needed!
Posted by Harald Mueller on 07 Apr 1998, 1:35 PM
A general ;-) remark: making code clear is still about conveying
intentions to code readers, not about functionality (the
compiler will understand everything, even the most obfuscated code).
Clearness thus comes from describing well what a certain construct
should accomplish. The battle here is always: Is the code itself clear enough, or
should I document it? The trade-off is clear: "Pure code" cannot
become inconsistent; on the other hand, it is not clear how to
document non-trivial intentions to a code reader.
The way out, I think, are idioms: If I write this or that,
I mean this and that (see Kent Beck's book on Smalltalk
idioms; I dont know whether there is already one that is as clear
for Java). So, to return to the CoffeeCup constructors, I think the code
will always remain unclear until either
(a) one documents that some constructors are "basic", others
are "convenience constructors"; or
(b) one has an idiom that makes that clear without comments
(e.g.: A constructor whose parameter profile is the prefix of
another constructor's parameter profile will always call the
"longer" constructor, with "suitable defaults" for the additional
parameters. And (e.g.): "Suitable defaults" are the defaults
defined in Java; or: ... defaults are taken from a global
DefaultEnvironment object (e.g. returned by a static method on
the CoffeeCup class); or whatever else. I would hope that rules/idioms like these would avoid the
lenghty "I like that better" discussions, just by making clear
what is (implicitly) "understood" and what has to be
(at least crudely) documented [in a previous (Smalltalk) project
under a tight schedule, we had no time to write nice comments;
however, we always provided one of the following: "action method" [meant to do something "real"]
"access method" (not needed in Java - indicated by the set/get idiom)
"convenience method" (e.g. shortened parameter profile, with defaults)
"factory method" (i.e. constructor; new and new: were not annotated at all) Most of the time, this conveyed the intent of the method quite well -
and also the need for further documentation: Action methods would
need one first, the rest "later" (in practice ... well ... never). Harald
Replies:
|
