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: squeak-dev-bounces at lists.squeakfoundation.org
[mailto:squeak-dev-bounces at lists.squeakfoundation.org] On Behalf Of Boris
Popov
Sent: Friday, June 16, 2006 1:43 AM
To: The general-purpose Squeak developers list;
squeak-dev at lists.squeakfoundation.org
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

boris at deepcovelabs.com

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: squeak-dev-bounces at lists.squeakfoundation.org on behalf of Milan
Zimmermann
Sent: Thu 15/06/2006 10:43 PM
To: squeak-dev at lists.squeakfoundation.org
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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20060616/90244def/attachment.htm