[Tutor] Do you use doctests to show API use even when you normally use unit tests?

[DL Neil]

On 4/05/20 12:17 PM, Cameron Simpson wrote:
> On 04May2020 08:44, DL Neil <PyTutor at danceswithmice.info> wrote:
> [...snip...]
>> However, one of the irritating, almost arrogant, features of many 
>> F/LOSS projects (not specifically Python then) is the way some authors 
>> insist that the way to learn about their grand-creation, is to read 
>> the code (cf RTFM!). This is true, and doubly-so for security reasons, 
>> but... it is also a high 'barrier to entry'. Many a project would 
>> receive better take-up if it explained its API, at least with How-to 
>> examples. Initial application would be a lot faster (and 
>> motivational!), per @Alan's comment. [...]
> 
> I also find this irritating, but for other reasons.
> 
> Reading the code is indeed a great way to learn how something was 
> implemented, and in principle to learn what assumptions the author may 
> have made which are not clarified in the documentation, and/or what 
> bugs/limitations the implementation may have which are no elucidated in 
> the documentation. _If_ the code is accessable, meaning here "readable".
> 
> However, it is a LOUSY way to learn about the problem that is being 
> solved, and about the _semantics_ which are purported to be supplied. 
> Here I mean that the code will tell you what happens. But only the docs 
> will tell you which implementation specific aspects of the code are to 
> be relied upon by the user of the code.
...
> I trip over devs all the time who confuse the implementation with the 
> specification. And I hate it.
...

> Grumblingly,


Don't feel such "grumbling" is negative, if we can learn/improve from it 
(but a grumpy, old, man would say that, wouldn't he?)


A question for all (cf addressing only @Cameron):-

Most programmers (and programming courses) have difficulty handling and 
covering documentation. Even those who consciously, and conscientiously, 
attempt to behave in a responsible and professional fashion.

Ref "implementation with the specification" (above) Is this (in part) 
because we do confuse these two?

I attempt to carry as much of the specification (in distilled form) 
forward, as possible. So, design docs feature restatements of the 
specification. Similarly, such design docs are 'carried forward' into 
code outlines. However, the way the code implements the identified needs 
may not lend itself to carrying such information forward into (say) 
class or method docstrings.

However, when it comes to writing tests - at the level of basic 
unit-testing, are we testing against "implementation" or 
"specification". At an higher level of testing, does that change? So, 
when we design our tests (back to earlier-posted 'TDD heresy'), should 
we carry-forward "design" documentation cf "implementation", neither, or 
both?


Another counter-argument/discussion-point: with doctests particularly - 
but maybe not (?) do we find that our code has become 'cluttered' with 
all of this natural-language, which makes it unnecessarily difficult to 
see our Python?
-- 
Regards =dn