<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:st1="urn:schemas-microsoft-com:office:smarttags" xmlns="http://www.w3.org/TR/REC-html40">
<head>
<meta http-equiv=Content-Type content="text/html; charset=us-ascii">
<meta name=Generator content="Microsoft Word 11 (filtered medium)">
<!--[if !mso]>
<style>
v\:* {behavior:url(#default#VML);}
o\:* {behavior:url(#default#VML);}
w\:* {behavior:url(#default#VML);}
.shape {behavior:url(#default#VML);}
</style>
<![endif]-->
<title>Re: Better write a test or a comment for a given method? Was: Re:Two
Squeak-related bugs and three questions</title>
<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags"
name="PostalCode"/>
<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags"
name="country-region"/>
<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags"
name="City"/>
<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags"
name="place"/>
<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags"
name="Street"/>
<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags"
name="address"/>
<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags"
name="PersonName"/>
<!--[if !mso]>
<style>
st1\:*{behavior:url(#default#ieooui) }
</style>
<![endif]-->
<style>
<!--
/* Font Definitions */
@font-face
{font-family:Tahoma;
panose-1:2 11 6 4 3 5 4 4 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0in;
margin-bottom:.0001pt;
font-size:12.0pt;
font-family:"Times New Roman";}
a:link, span.MsoHyperlink
{color:blue;
text-decoration:underline;}
a:visited, span.MsoHyperlinkFollowed
{color:blue;
text-decoration:underline;}
p
{mso-margin-top-alt:auto;
margin-right:0in;
mso-margin-bottom-alt:auto;
margin-left:0in;
font-size:12.0pt;
font-family:"Times New Roman";}
span.EmailStyle18
{mso-style-type:personal-reply;
font-family:Arial;
color:navy;}
@page Section1
{size:8.5in 11.0in;
margin:1.0in 1.25in 1.0in 1.25in;}
div.Section1
{page:Section1;}
-->
</style>
</head>
<body lang=EN-US link=blue vlink=blue>
<div class=Section1>
<p class=MsoNormal><font size=2 color=navy face=Arial><span style='font-size:
10.0pt;font-family:Arial;color:navy'>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. <o:p></o:p></span></font></p>
<p class=MsoNormal><font size=2 color=navy face=Arial><span style='font-size:
10.0pt;font-family:Arial;color:navy'><o:p> </o:p></span></font></p>
<p class=MsoNormal><font size=2 color=navy face=Arial><span style='font-size:
10.0pt;font-family:Arial;color:navy'>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. <o:p></o:p></span></font></p>
<p class=MsoNormal><font size=2 color=navy face=Arial><span style='font-size:
10.0pt;font-family:Arial;color:navy'><o:p> </o:p></span></font></p>
<p class=MsoNormal><font size=2 color=navy face=Arial><span style='font-size:
10.0pt;font-family:Arial;color:navy'>As for comments we could really use more! <o:p></o:p></span></font></p>
<p class=MsoNormal><font size=2 color=navy face=Arial><span style='font-size:
10.0pt;font-family:Arial;color:navy'><o:p> </o:p></span></font></p>
<p class=MsoNormal><font size=2 color=navy face=Arial><span style='font-size:
10.0pt;font-family:Arial;color:navy'>Ron Teitelbaum<o:p></o:p></span></font></p>
<p class=MsoNormal><font size=2 color=navy face=Arial><span style='font-size:
10.0pt;font-family:Arial;color:navy'><o:p> </o:p></span></font></p>
<div style='border:none;border-left:solid blue 1.5pt;padding:0in 0in 0in 4.0pt'>
<div>
<div class=MsoNormal align=center style='text-align:center'><font size=3
face="Times New Roman"><span style='font-size:12.0pt'>
<hr size=2 width="100%" align=center tabindex=-1>
</span></font></div>
<p class=MsoNormal><b><font size=2 face=Tahoma><span style='font-size:10.0pt;
font-family:Tahoma;font-weight:bold'>From:</span></font></b><font size=2
face=Tahoma><span style='font-size:10.0pt;font-family:Tahoma'>
squeak-dev-bounces@lists.squeakfoundation.org
[mailto:squeak-dev-bounces@lists.squeakfoundation.org] <b><span
style='font-weight:bold'>On Behalf Of </span></b>Boris Popov<br>
<b><span style='font-weight:bold'>Sent:</span></b> Friday, June 16, 2006 1:43
AM<br>
<b><span style='font-weight:bold'>To:</span></b> <st1:PersonName w:st="on">The
general-purpose Squeak developers list</st1:PersonName>;
squeak-dev@lists.squeakfoundation.org<br>
<b><span style='font-weight:bold'>Subject:</span></b> Best comment award of
2006 (was: Better write a test or a comment?)</span></font><o:p></o:p></p>
</div>
<p class=MsoNormal><font size=3 face="Times New Roman"><span style='font-size:
12.0pt'><o:p> </o:p></span></font></p>
<div id=idOWAReplyText44127>
<div>
<p class=MsoNormal><font size=2 color=black face=Arial><span style='font-size:
10.0pt;font-family:Arial;color:black'>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,</span></font><o:p></o:p></p>
</div>
<div>
<p class=MsoNormal><font size=3 face="Times New Roman"><span style='font-size:
12.0pt'> <o:p></o:p></span></font></p>
</div>
<div>
<p class=MsoNormal><font size=2 face=Arial><span style='font-size:10.0pt;
font-family:Arial'>"If you think this method is wrong, think again"</span></font><o:p></o:p></p>
</div>
<div>
<p class=MsoNormal><font size=3 face="Times New Roman"><span style='font-size:
12.0pt'> <o:p></o:p></span></font></p>
</div>
<div>
<p class=MsoNormal><font size=2 face=Arial><span style='font-size:10.0pt;
font-family:Arial'>Pretty effective at keeping people away when they tend to
blame the framework for every issue they can't understand, myself
included ;)</span></font><o:p></o:p></p>
</div>
<div>
<p class=MsoNormal><font size=3 face="Times New Roman"><span style='font-size:
12.0pt'> <o:p></o:p></span></font></p>
</div>
</div>
<div id=idSignature91741>
<div>
<p class=MsoNormal><font size=2 color=black face=Arial><span style='font-size:
10.0pt;font-family:Arial;color:black'>-Boris<br>
<br>
--<br>
+1.604.689.0322<br>
DeepCove Labs Ltd.<br>
4th floor <st1:Street w:st="on"><st1:address w:st="on">595 Howe Street</st1:address></st1:Street><br>
<st1:place w:st="on"><st1:City w:st="on">Vancouver</st1:City>, <st1:country-region
w:st="on">Canada</st1:country-region> <st1:PostalCode w:st="on">V6C 2T5</st1:PostalCode></st1:place><br>
<br>
boris@deepcovelabs.com<br>
<br>
CONFIDENTIALITY NOTICE<br>
<br>
This email is intended only for the persons named in the message<br>
header. Unless otherwise indicated, it contains information that is<br>
private and confidential. If you have received it in error, please<br>
notify the sender and delete the entire message including any<br>
attachments.<br>
<br>
Thank you.</span></font><o:p></o:p></p>
</div>
</div>
<div>
<p class=MsoNormal><font size=3 face="Times New Roman"><span style='font-size:
12.0pt'><o:p> </o:p></span></font></p>
<div class=MsoNormal align=center style='text-align:center'><font size=3
face="Times New Roman"><span style='font-size:12.0pt'>
<hr size=2 width="100%" align=center tabIndex=-1>
</span></font></div>
<p class=MsoNormal style='margin-bottom:12.0pt'><b><font size=2 face=Tahoma><span
style='font-size:10.0pt;font-family:Tahoma;font-weight:bold'>From:</span></font></b><font
size=2 face=Tahoma><span style='font-size:10.0pt;font-family:Tahoma'>
squeak-dev-bounces@lists.squeakfoundation.org on behalf of Milan Zimmermann<br>
<b><span style='font-weight:bold'>Sent:</span></b> Thu 15/06/2006 10:43 PM<br>
<b><span style='font-weight:bold'>To:</span></b>
squeak-dev@lists.squeakfoundation.org<br>
<b><span style='font-weight:bold'>Subject:</span></b> Re: Better write a test
or a comment for a given method? Was: Re:Two Squeak-related bugs and three
questions</span></font><o:p></o:p></p>
</div>
<div>
<p style='margin-bottom:12.0pt'><font size=2 face="Times New Roman"><span
style='font-size:10.0pt'>On 2006 June 15 15:20, Markus Gaelli wrote:<br>
> On Jun 15, 2006, at 8:50 PM, Milan Zimmermann wrote:<br>
<br>
(actually it was Tim :) )<br>
<br>
> >> The old joke "comments? why<br>
> >> do think it's called code?" sums up the antithesis of
responsible<br>
> >> programming that seems to be the normal approach. Yes, reading
the<br>
> >> code tells you what it *does* do (until you find a compiler bug
for<br>
> >> example) but it tells you nothing about what it was intended to
do,<br>
> >> what spec it was putatively meeting or what limits on its<br>
> >> functionality were known about.<br>
><br>
> So did tests, pre- / postconditions and counterexamples -- if they<br>
> were known to focus on a given method.<br>
><br>
> If in doubt whether I should write a comment or a test, I'd go for<br>
> the test.<br>
> Nice thing is, that the test not only helps other developers to<br>
> understand the system, but also the computer to automatically...test it.<br>
<br>
I agree with what you are saying with two comments.<br>
<br>
While tests are for asserting
whether a method, instance, or module behave as<br>
expected under given inputs (including whether the code under test handles<br>
broken preconditions etc), I would say comments are necessary to describe<br>
intent, purpose, broader "cultural" circumstances, design decisions,<br>
including dead end streets encountered when the code (method, instance,<br>
module) was designed and developed.<br>
<br>
> If I had enough time, I'd write both.><br>
<br>
Yes, but I would argue (this is my
perception) that writing good comments<br>
takes about 10% of the time of writing good comprehensive tests, so if there<br>
is enough time writing good tests, there is always time to start with a<br>
helpful comment describing intent and purpose (etc - as above). For that<br>
reason, I am not sure in practice writing test first and documentation second<br>
is the best approach, as writing a really "complete" test for a
module or<br>
application may be close in time to writing the module or application self,<br>
while writing comments can give good guidance for future readers of the code,<br>
as well as present or future writers of code tests.<br>
<br>
> If there were a discussion to introduce a "documentation space"
shown<br>
> next to a given method to document it (as it is the case for classes<br>
> right now) I'd strongly argue to use it for tests -- and not for<br>
> comments.<br>
<br>
I don't want to argue with that (I think your assumption is if option was<br>
given to only have one such space), but I would really miss my comments (of<br>
the type described above), written to save my (and hopefully others')<br>
backside in the future.<br>
<br>
> You can find a suggestion for explicitly linking a test to a method<br>
> here:<br>
> <a href="http://www.iam.unibe.ch/~scg/Archive/Papers/">http://www.iam.unibe.ch/~scg/Archive/Papers/</a><br>
> Gael04cLinkingMethodsAndTests.pdf<br>
><br>
<br>
I think I read your article in the past :) - rereading it I like it, if I<br>
understand, the meta model ties one test method to each method, does it also<br>
play any role in defining the test suites?<br>
<br>
> Today I would either use method properties or blocks to denote the<br>
> method under test (and not comments anymore...;-)<br>
> A better example than testing an accessor (as used in the screenshot<br>
> of above paper - boooring) would help also to illustrate the power of<br>
> a five-pane browser, where the fifth pane included tests.<br>
<br>
yes<br>
<br>
> Note that we could also easily extract the concrete types for the<br>
> method under test - and - if we returned the result of a sampled<br>
> method, also the instance variables of the class of the resulting<br>
> object.<br>
<br>
So if developer writes tests first, he/she defines the argument types and<br>
return types that are passed to and returned from the tested methods, and the<br>
types then can be extracted from the tests by tools, making type declaration<br>
unneeded, is that what you are saying, or am I misunderstanding..<br>
<br>
Thanks <st1:City w:st="on"><st1:place w:st="on">Milan</st1:place></st1:City><br>
<br>
<br>
><br>
> Cheers,<br>
><br>
> Markus</span></font><o:p></o:p></p>
</div>
</div>
</div>
</body>
</html>