[Tutor] Suggestions about documenting a function

[Alan Gauld]

"Jorge Azedo" <jazedo at netcabo.pt> wrote

> import random
>
> def randomList(n1,n2,len):
>    '''n1-n2 range of numbers, len - length of the final list
>
>    Returns a list'''

Don't worry too much about writing the doc string to fit in
the IDE hint box. Think more about how it will look when
people use help() or __doc__ to print the documentation.

Specifically this doc string isn't actually too helpful since
it only tells me the data types of the inputs and outputs
but gives no clues about the actual purpose of the function.
Specifically it doesn't make it clear that the returned list
will contain *unique* random numbers from the range

>    i=0
>    rndlist=[]
>    if len > n2:
>        return 'The length of the list must be greater than n2'

Huh?
This can never work.
If I use 99,100,101

that implies you will give me 101 unique numbers
between 99 and 100... Surely the constraint should be that

len < n2-n1

Also, what happens if n1 > n2?
(This is also a bug in randint IMHO...)


> before he runs it, but I can't think of a short enough way to say it 
> so
> that it still appears in that little window that shows up when  you
> start writing the arguments to a function.

Don't even try... or if you must keep the input summary on one
line and expand the second paragraph to describe what it does.

BTW One common notation for defining functoion signatures is

param,param,param... -> result.

So in your case you could use:

(n1 int, n2 int, length int) -> list : n1 < n2, ln < n2-n1

which is more concise and includes the constraints...
but still doesn't convey the intent.

HTH
-- 
Alan Gauld
Author of the Learn to Program web site
http://www.freenetpages.co.uk/hp/alan.gauld