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

Milan Zimmermann milan.zimmermann at sympatico.ca
Fri Jun 16 05:43:06 UTC 2006


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



More information about the Squeak-dev mailing list