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:

I like your comment, because...

Posted by Bill Venners on 08 Apr 1998, 2:30 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.
>
I agree.

> 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).
>
And when one does write comments, they should explain the
programmer's intentions and the context in which the code was
written. For example, why the code had to be written this way
and not another way, etc.

> 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).
>
Yes, I basically agree with you, except that I think this
forum could be a place where Java idioms are uncovered, proposed,
debated, and discussed.

I would call the way I do constructors, which you described
above in item b, as one of my own, personal idioms. I always
do constructors that way, and I've seen a lot of other people
do it that way. (In C++ and Java.) To me it seems obvious that
the shorter ones are convenience constructors.

But can I say it's a global Java idiom? It seems idioms, like
patterns, arise out of the practical experience of many and are
then recognized. I don't think I have broad enough experience
to say this or that is an idiom. Seems to me the process
requires community debate.

And I think that part of that debate needs to be "I do such
and such in this way because..." Or even, "I like it this
way, because..." Although the main thing is discovering what
approach everyone already uses and recognizes, I think stating
the merits of the approach (the "because...") is an
important part of the process.

I'll check out Kent Beck's book. We should be able to carry a
lot of design and implementation idioms over from Smalltalk
into Java. (At least it can inform the debate.) I haven't ever
done any Smalltalk programming. Before Java, I was immersed
in the world of C++.

bv