#13628 closed (fixed)
Documentation should discourage the usage of doctests
Reported by: | Dougal Matthews | Owned by: | Dougal Matthews |
---|---|---|---|
Component: | Documentation | Version: | dev |
Severity: | Keywords: | ||
Cc: | Triage Stage: | Accepted | |
Has patch: | yes | Needs documentation: | no |
Needs tests: | no | Patch needs improvement: | no |
Easy pickings: | no | UI/UX: | no |
Description
At the moment the documentation described both doctest and unit tests without giving the reader and guidance to one or the other. It is generally agree'd that unit tests are a better choice. I have added a patch with a small patch that adds a note to reflect this.
However, I'm not sure if this reflects a bigger problem - should unit tests be described first and docetests second so that the reader doesn't read through that section only to find out its not recommended? Or should the note be added to the top and further emphasised?
Attachments (3)
Change History (14)
by , 14 years ago
Attachment: | unitdest-warning.diff added |
---|
comment:1 by , 14 years ago
Has patch: | set |
---|
comment:2 by , 14 years ago
Patch needs improvement: | set |
---|
comment:3 by , 14 years ago
Triage Stage: | Unreviewed → Accepted |
---|
comment:4 by , 14 years ago
Owner: | changed from | to
---|---|
Status: | new → assigned |
by , 14 years ago
Attachment: | doctest-warning.diff added |
---|
comment:5 by , 14 years ago
Patch needs improvement: | unset |
---|
Added a new patch that makes more sense. Apologies for the previous rush sloppy version.
comment:6 by , 14 years ago
Triage Stage: | Accepted → Ready for checkin |
---|
comment:7 by , 14 years ago
Patch needs improvement: | set |
---|---|
Triage Stage: | Ready for checkin → Accepted |
I'm not happy with the patch as it is. We still have other statements on that page that suggest that both frameworks are equally valid choices. And we already have a section entitled "which should I use" (which is the area where it is logical to put this change), and that section is actually fairly positive towards doctests, calling them Pythonic, implying that they are for experienced developers, when actually the experience of most Django developers leads us away from them for serious testing. The problem is that while they are good for quick, simple testing, and good for some simple example code, they are not very good if you want to produce either high quality, comprehensive tests or high quality documentation.
So, a bit of a rework of that page is in order if we want to avoid contradicting ourselves:
- switching to put unittests first like you suggest (which requires a bit of rework of the sections themselves)
- reworking the sentence that says "You can choose the test framework you like, depending on which syntax you prefer" to be less ambivalent (maybe just remove it)
- and modifying the section "which should I use" to emphasise these things about the limitations of doctests and when they are appropriate.
Thanks
comment:8 by , 14 years ago
Patch needs improvement: | unset |
---|
comment:9 by , 14 years ago
Resolution: | → fixed |
---|---|
Status: | assigned → closed |
If a committer approves this, the grammar needs to be fixed in the patch.