Re: document your test files

I disagree, though not strongly. Each test has a message associated with it, and IMO best practice is for the author to strive to make those messages suffice as documentation, falling back to comments only when necessary.

--
Marvin Humphrey
Rectangular Research ― http://www.rectangular.com

Comment on Re: document your test files

Replies are listed 'Best First'.
Re^2: document your test files by DrHyde (Prior) on Jul 31, 2006 at 09:45 UTC
The text tells you what is being tested, not how it is being tested. I quite often have tests which rely on the results of previous tests, or which perform convoluted backflips to massage my objects' state into something needed for the next test. This sort of thing, I have realised, must be commented. Not because it's useful to you, as you should be relying on the module's documentation and not its tests to see what it does and how to use it. No, the tests should be commented for the same reason that the module being tested should have comments - because it makes it easier for me to fix bugs or add functionality later. Expect me to finish fixing all my test code ... never.	[reply]
Re^2: document your test files by grantm (Parson) on Jul 31, 2006 at 09:12 UTC
I disagree, though not strongly. Each test has a message associated with it ... So you're not disagreeing you're agreeing :-) I suspect that the OP is referring to the style of tests which are common in distributions that predate Test::Simple and Test::More. Back in the 'old days', a test assertion looked like this: `ok(1)` I was working with just such a test file this week and I would dearly have loved to see a message associated with each test.	[reply] [d/l]