I think that Python's doctests have shown this to be a greyer area than this. Not all tests can fit nicely next to function definitions, but a few well-chosen ones are both fantastic documentation and not too cluttery.
Doc tests are a poor solution precisely because they are difficult to edit. The solved a non-problem and made writing documentation AND tests more difficult.
Instead of writing tests in strings, the documentation tool should have been modified to render that code _in_ the documentation.
Doc tests are butt-ugly in several ways. Code shouldn't be written in strings, and they take twice as much vertical space as they need (which is a problem because monitors are typically used much wider than they are tall).
I agree with you in that managing real code in a place that gets less frequently executed is a bear, but I wanted to emphasize the value of having tests very near to the primary documentation for a function. That's a complete win, I feel.
Tests should absolutely be next to the code. The test should make it into the documentation. Code is documentation and should make it into the generated documentation, not the first thing you see but it should be there along with commit history, etc.
If that ended up nicely formatted beneath the definition of `foo` in the documentation I would recommend it wholeheartedly. In practice it doesn't happen, sadly.
Thank you! I never had any idea this kind of things exists in python... I can already see some code that would benefit from this (it would be insane to put it everywhere of course).
Instead of writing tests in strings, the documentation tool should have been modified to render that code _in_ the documentation.