Add links in manual to test_modules.
I am already making use of the source links added to the 3.2 manuals. I propose that we also add links to test-modules where appropriate, both in the language and library manuals. 1. It would help developers. 2. It could help users. Each test module is a set of examples of how to use the corresponding aspect of Python both correctly and incorrectly, with many corner cases that might not be clear from the manual. Each test module should exercise every feature of the stdlib module or other area covered. In addition, unlike external sets of examples, the test suite is updated and expected to run with the corresponding version. As language and implementation tests are better separated, people could better see which behavior is which. 3. Exposing the test suite would expose deficiencies and encourage improvements. -- Terry Jan Reedy
On Fri, Mar 18, 2011 at 11:28:13PM -0400, Terry Reedy wrote:
I propose that we also add links to test-modules where appropriate, both in the language and library manuals.
I hope this is not motivated from the other discussion we were having to link example snippets. I find link to source modules helpful , but I not sure how helpful it would be to link the tests, as it has chances of adding to confusing given the xUnit test 'unittests' we have in our tests module. When looking for usage assistance people look for complete scripts rather than test scripts. Source module link help to provide 'more-accurate' information as lot many times code explains better than words. So, +0 from me. -- Senthil
Ick, no. We do all sorts of dodgy stuff in our test suite to stress implementations, probe obscure corner cases, double up on checks based on where and when bugs happened to be reported. Large parts of it are written to make the tests easier to write, not because they reflect any kind of idiomatic code, or good ways of doing things in a real application. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
Nick Coghlan wrote:
But surely a test suite counts as a real application? It's likely to be bigger than the "actual" application or library, it still needs to be maintained, and is more likely to have bugs (on account of there being no test suite for the tests). Speaking for myself, I find code reuse and design of my test suites to be one of the harder parts of writing code. Perhaps I'd learn something from the Python tests, even if only "everyone has trouble writing good unit-tests" *wink* As I see it, the main benefit of Terry's suggestion is that it may encourage developers to write new tests for the standard library, or to refactor the existing tests. +0.5 from me. -- Steven
On Sat, 19 Mar 2011 17:45:00 +1100 Steven D'Aprano <steve@pearwood.info> wrote:
I agree with Nick, the test suite does not give "examples" of how to use the APIs - and often it will actually invoke semi-private APIs in order to easy testing. Claiming the test suite has any educational value would be a disservice to our users. -1 from me. Regards Antoine.
On Fri, Mar 18, 2011 at 11:45 PM, Steven D'Aprano <steve@pearwood.info> wrote:
I'm with Nick. Tests (at least the ones we have for the standard library) are rarely any good as example code for the modules being tested. They may be great if you want to learn to write tests or if you want to contribute to the stdlib, but they are easy enough to find. Linking them from the docs is sending people to a body of code that most people should never peruse. The one exception is that the tests can show language/library lawyers how something is supposed to behave in more detail than docs, without having to actually read the source. But again that's pretty advanced and the people interested in that stuff know where to go. -- --Guido van Rossum (python.org/~guido)
On Fri, Mar 18, 2011 at 11:28:13PM -0400, Terry Reedy wrote:
I propose that we also add links to test-modules where appropriate, both in the language and library manuals.
I hope this is not motivated from the other discussion we were having to link example snippets. I find link to source modules helpful , but I not sure how helpful it would be to link the tests, as it has chances of adding to confusing given the xUnit test 'unittests' we have in our tests module. When looking for usage assistance people look for complete scripts rather than test scripts. Source module link help to provide 'more-accurate' information as lot many times code explains better than words. So, +0 from me. -- Senthil
Ick, no. We do all sorts of dodgy stuff in our test suite to stress implementations, probe obscure corner cases, double up on checks based on where and when bugs happened to be reported. Large parts of it are written to make the tests easier to write, not because they reflect any kind of idiomatic code, or good ways of doing things in a real application. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
Nick Coghlan wrote:
But surely a test suite counts as a real application? It's likely to be bigger than the "actual" application or library, it still needs to be maintained, and is more likely to have bugs (on account of there being no test suite for the tests). Speaking for myself, I find code reuse and design of my test suites to be one of the harder parts of writing code. Perhaps I'd learn something from the Python tests, even if only "everyone has trouble writing good unit-tests" *wink* As I see it, the main benefit of Terry's suggestion is that it may encourage developers to write new tests for the standard library, or to refactor the existing tests. +0.5 from me. -- Steven
On Sat, 19 Mar 2011 17:45:00 +1100 Steven D'Aprano <steve@pearwood.info> wrote:
I agree with Nick, the test suite does not give "examples" of how to use the APIs - and often it will actually invoke semi-private APIs in order to easy testing. Claiming the test suite has any educational value would be a disservice to our users. -1 from me. Regards Antoine.
On Fri, Mar 18, 2011 at 11:45 PM, Steven D'Aprano <steve@pearwood.info> wrote:
I'm with Nick. Tests (at least the ones we have for the standard library) are rarely any good as example code for the modules being tested. They may be great if you want to learn to write tests or if you want to contribute to the stdlib, but they are easy enough to find. Linking them from the docs is sending people to a body of code that most people should never peruse. The one exception is that the tests can show language/library lawyers how something is supposed to behave in more detail than docs, without having to actually read the source. But again that's pretty advanced and the people interested in that stuff know where to go. -- --Guido van Rossum (python.org/~guido)
participants (7)
-
Antoine Pitrou -
Guido van Rossum -
Nick Coghlan -
Senthil Kumaran -
Steven D'Aprano -
Terry Reedy -
Westley Martínez