[Grok-dev] Re: Grok Widgets / Fields (Was Re: Re: [grok-br] Grok 1.0 and beyond)

[Tres Seaver]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Martijn Faassen wrote:
> Sebastian Ware wrote:
> [snip]
>> Maybe I should try to get into the formlib stuff again. The code seems 
>> to be well documented, but sometimes I have difficulties translating the 
>> doctest type documentation into working code.
> 
> You're not the only one. It's pretty normal. I always console myself by 
> saying, well, this doctest is a lot better than having just plain unit 
> tests (or *nothing*).

Not IMHO:  If the doctests are not useful as documentation, then they
are *worse* than the equivalent (well-written) unit tests:  the lack of
test isolation, and the pain of writing "edge-case" tests in doctest,
make it a poorer unit testing setup than unit tests.

One effect I'm not sure people have noticed about doctests:  while the
examples stay current (because the testing framework borks if they
don't), the narrative tends to bitrot, even if it was well written in
the beginning.  Because the core developers aren't likely to revisit the
narrative (after all, they understand the package), there is no
corrective for either poorly-written narrative or bit-rotted narrative
except to have somebody like Sebastian stumble across it ane complain.


Tres.
- --
===================================================================
Tres Seaver          +1 540-429-0999          tseaver at palladion.com
Palladion Software   "Excellence by Design"    http://palladion.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFHiPeK+gerLs4ltQ4RAq45AKChSoTHQQV6dkY3jPQ48aNFmGDA0QCgoO2+
enR722ytyS7Gts/yh2m5sSQ=
=2wSZ
-----END PGP SIGNATURE-----