Back to the issue... (was RE: Squeak coding style...)
tim at sumeru.stanford.edu
Wed Mar 3 05:29:11 UTC 2004
Lex Spoon wrote:
> Then it is utterly pointless to go through putting comments like "a
> LEVariable is a lambda expression variable" and "a LEApplication is a
> lambda expression application". If you know what a lambda expression
> then you don't want a comment in the subclasses.
I think that's probably a poor characterisation. Class comments
shouldn't merely be something like that. They _ought_ to explain the
purpose and usage, the specifics of any limitations, stuff like that.
I'm not going to claim that many class comments I've seen (let alone
written) really meet this.
> Sure, put a comment in LargeInteger to say what "large" means. But a
> comment would be useless in the two subclasses.
I disagree, obviously given my above comments.
LPI should becommented to explain that it represents only positive
values, that the code may need to create LNIs as a result of
subtractions, that normalisation may produce SmallIntegers(we recently
had list messages relating to some confusion about this).
LNI would benefit from explanations of a similar nature but obviously
LPIs are created asa result of -ve * -ve and all that.
Basically I would claim that there are menaingful and useful comments
for pretty much any class. When we implement even a trivial class we
need to remember that it might not be trivial to someone else. Reviews
ought to be a time when this is checked and 'enforced'.
More information about the Squeak-dev