Smalltalk › Squeak › Squeak - Dev

Two Squeak-related bugs and three questions

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

22 messages Options

Ron Teitelbaum

RE: Best comment award of 2006 (was: Better write a test or a comment?)

Re: Better write a test or a comment for a given method? Was: Re:Two Squeak-related bugs and three questions

Once after a long argument about whether or not to include a snapshot of data or to leave the system more dynamic I named a table in the database StupidSnapshot. The class was just snapshot but the table name in oracle was different. It’s amazing to me how many people saw that table name. I had DBA’s calling me up and even though there were almost a thousand tables they still asked me, what’s with StupidSnapshot. It even turned out that there was some benefit to the table even if it wasn’t really worth the extra space. It definitely taught me to watch what you put in code.

I even got called on it once with some squeak stuff when I picked some bad temp names for Associations! Anyway not comments, but code.

As for comments we could really use more!

Ron Teitelbaum

From: [hidden email] [mailto:[hidden email]] On Behalf Of Boris Popov
Sent: Friday, June 16, 2006 1:43 AM
To: The general-purpose Squeak developers list; [hidden email]
Subject: Best comment award of 2006 (was: Better write a test or a comment?)

Lets lighten up the topic a bit, shall we? How about we all submit our nominations for "most-useful-comment-i-have-seen" award of 2006, here's one from the bowels of the transaction code in our db framework,

"If you think this method is wrong, think again"

Pretty effective at keeping people away when they tend to blame the framework for every issue they can't understand, myself included ;)

-Boris

--
+1.604.689.0322
DeepCove Labs Ltd.
4th floor 595 Howe Street
Vancouver, Canada V6C 2T5

[hidden email]

CONFIDENTIALITY NOTICE

This email is intended only for the persons named in the message
header. Unless otherwise indicated, it contains information that is
private and confidential. If you have received it in error, please
notify the sender and delete the entire message including any
attachments.

Thank you.

From: [hidden email] on behalf of Milan Zimmermann
Sent: Thu 15/06/2006 10:43 PM
To: [hidden email]
Subject: Re: Better write a test or a comment for a given method? Was: Re:Two Squeak-related bugs and three questions

On 2006 June 15 15:20, Markus Gaelli wrote:
> On Jun 15, 2006, at 8:50 PM, Milan Zimmermann wrote:

(actually it was Tim :) )

> >> The old joke "comments? why
> >> do think it's called code?" sums up the antithesis of responsible
> >> programming that seems to be the normal approach. Yes, reading the
> >> code tells you what it *does* do (until you find a compiler bug for
> >> example) but it tells you nothing about what it was intended to do,
> >> what spec it was putatively meeting or what limits on its
> >> functionality were known about.
>
> So did tests, pre- / postconditions and counterexamples -- if they
> were known to focus on a given method.
>
> If in doubt whether I should write a comment or a test, I'd go for
> the test.
> Nice thing is, that the test not only helps other developers to
> understand the system, but also the computer to automatically...test it.

I agree with what you are saying with two comments.

While tests are for asserting whether a method, instance, or module behave as
expected under given inputs (including whether the code under test handles
broken preconditions etc), I would say comments are necessary to describe
intent, purpose, broader "cultural" circumstances, design decisions,
including dead end streets encountered when the code (method, instance,
module) was designed and developed.

> If I had enough time, I'd write both.>

Yes, but I would argue (this is my perception) that writing good comments
takes about 10% of the time of writing good comprehensive tests, so if there
is enough time writing good tests, there is always time to start with a
helpful comment describing intent and purpose (etc - as above). For that
reason, I am not sure in practice writing test first and documentation second
is the best approach, as writing a really "complete" test for a module or
application may be close in time to writing the module or application self,
while writing comments can give good guidance for future readers of the code,
as well as present or future writers of code tests.

> If there were a discussion to introduce a "documentation space" shown
> next to a given method to document it (as it is the case for classes
> right now) I'd strongly argue to use it for tests -- and not for
> comments.

I don't want to argue with that (I think your assumption is if option was
given to only have one such space), but I would really miss my comments (of
the type described above), written to save my (and hopefully others')
backside in the future.

> You can find a suggestion for explicitly linking a test to a method
> here:
> http://www.iam.unibe.ch/~scg/Archive/Papers/
> Gael04cLinkingMethodsAndTests.pdf
>

I think I read your article in the past :) - rereading it I like it, if I
understand, the meta model ties one test method to each method, does it also
play any role in defining the test suites?

> Today I would either use method properties or blocks to denote the
> method under test (and not comments anymore...;-)
> A better example than testing an accessor (as used in the screenshot
> of above paper - boooring) would help also to illustrate the power of
> a five-pane browser, where the fifth pane included tests.

yes

> Note that we could also easily extract the concrete types for the
> method under test - and - if we returned the result of a sampled
> method, also the instance variables of the class of the resulting
> object.

So if developer writes tests first, he/she defines the argument types and
return types that are passed to and returned from the tested methods, and the
types then can be extracted from the tests by tools, making type declaration
unneeded, is that what you are saying, or am I misunderstanding..

Thanks Milan

>
> Cheers,
>
> Markus

Milan Zimmermann-2

Re: Better write a test or a comment for a given method? Was: Re: Two Squeak-related bugs and three questions

In reply to this post by Markus Gälli-3

Hi Markus,

On 2006 June 16 03:25, Markus Gaelli wrote:

> Hi Milan,
>
> This discussion about a "documentation space" for methods is purely
> hypothetical of course, as the concept of method comments is already
> built in the language and I guess nobody - including me - would
> understand the value of tearing out comments from methods into a
> separate pane. I just mentioned it to illustrate the problem, that
> method tests are not built in yet whether in the language/ meta model
> of smalltalk nor in the GUI - but we could, as we built in comments
> for classes onto a prominent place into the GUI recently...

I think what you are saying (and I agree) that things such as "class
comments", "method comments", and also "class tests" "method tests" should be
represented by objects in the framework (associated to their owner classes)

It seems that whether comments are presented to the user "inside the
text" (and extracted from there by the IDE, for example first comment in
method becomes the method comment), or presented in a separate pane is
probably an implementation detail. Tests should likely be in a separate
pane.... I do not know Squeak core that well, but from a search I just did it
seems that "class comments" are represented by "Comments" by cannot find any
member variable or object representing "method comments". But in any case, to
get back to tests, it does make lots of sense to associate tests in Squeak
framework to the elements (classes, methods) they test.

>
> >> You can find a suggestion for explicitly linking a test to a method
> >> here:
> >> http://www.iam.unibe.ch/~scg/Archive/Papers/
> >> Gael04cLinkingMethodsAndTests.pdf
> >
> > I think I read your article in the past :) - rereading it I like it,
> >
> :-)
> :
> > if I understand, the meta model ties one test method to each method,
>
> 0...n method commands to each method, yes. A method command could be
> also an example, or a counter example.
>
> > does it also
> > play any role in defining the test suites?
>
> The part of the meta model described in this paper does not mention
> suites. But the concept of suites is certainly a good one and the
> complete meta model reflects it.
> Note that we have the classic suites of independent tests like in
> SUnit. Denoting a test belonging to such a suite could be either done
> technically again by method properties (so the tests knows to which
> suites it belongs to) or by the approach of SUnit, where testsuites
> can be built to include several tests.

yes

>
> But I like to think about many tests also as "cascaded test suites"
> meaning that many long test methods could be broken down and composed
> out of several (one-)method commands. Not that I am saying, we should
> refactor the existing ones, as this does not bring much, but when
> writing new ones, one could consider to write smaller one-method
> tests, which return the "interesting object" they created or
> manipulated, so other tests could be written on top.

that makes lots of sense ...

> The advantages:
> smaller test methods should mean better readability in general, more
> reuse of complex test scenarios, faster tests, and concrete types
> that method commands provide.
>
> >> Note that we could also easily extract the concrete types for the
> >> method under test - and - if we returned the result of a sampled
> >> method, also the instance variables of the class of the resulting
> >> object.
> >
> > So if developer writes tests first, he/she defines the argument
> > types and
> > return types that are passed to and returned from the tested
> > methods, and the
> > types then can be extracted from the tests by tools, making type
> > declaration
> > unneeded, is that what you are saying, or am I misunderstanding..
>
> The developers write which concrete objects are used to test the method.
> Using some coverage tool an intelligent test tool can easily store
> the classes of the parameters _and_ result used by a given method
> under test - and display this to the developers, yes.

sounds good, thanks for commenting on this. In a really disciplined
tests-first environment I see how this would make any need for type
declaration go away, although only for the developer, not for the test
writer, and it seems in practice such test-type-extraction tool combined with
other tools that infere types could be very useful.

>
> I prepared an image used for that oopsla workshop on:
> http://www.iam.unibe.ch/~gaelli/oneMethodCommandsRDL.image.gz

I am playing with it - Let's say I go to Bank class>> code: method. I see 2
test in the right pane ... but I cannot figure out how to run them, but am
tired, will try again tomorrow.

>
> I display some "concrete examples" there using some bubble help as
> seen on a screenshot here:
> http://www.iam.unibe.ch/~gaelli/rdlScreenshot.png
>
> Could be the types certainly also....

yes - and thanks for your comments and image

Later Milan

>
> > Thanks Milan
>
> Thanks for commenting,
>
> Cheers,
>
> Markus