Path: csiph.com!usenet.pasdenom.info!weretis.net!feeder1.news.weretis.net!feeder.erje.net!eu.feeder.erje.net!newsfeed.xs4all.nl!newsfeed2.news.xs4all.nl!xs4all!newsgate.cistron.nl!newsgate.news.xs4all.nl!post.news.xs4all.nl!not-for-mail
To: python-list@python.org
From: Terry Reedy <tjreedy@udel.edu>
Subject: Re: python function parameters, debugging, comments, etc.
Date: Tue, 01 Oct 2013 19:56:41 -0400
References: <524B5288.1050709@mail.usask.ca>
Mime-Version: 1.0
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:24.0) Gecko/20100101 Thunderbird/24.0
In-Reply-To: <524B5288.1050709@mail.usask.ca>
Precedence: list
Newsgroups: comp.lang.python
Message-ID: <mailman.582.1380671823.18130.python-list@python.org>
Lines: 49
NNTP-Posting-Host: 2001:888:2000:d::a6
Xref: csiph.com comp.lang.python:55260

On 10/1/2013 6:54 PM, Chris Friesen wrote:

> Given the fact that function parameters do not specify types, when you're looking at someone else's code how the heck do you know what is expected for a given argument?  (Especially in a nontrivial system where the parameter is just passed on to some other function and may not be evaluated for several nested function calls.)
>
> Is the recommendation to have comments for each function describing the expected args?

Here is an example from the stdlib.
 >>> print(int.__doc__)
int(x=0) -> integer
int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments
are given.  If x is a number, return x.__int__().  For floating point
numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string,
bytes, or bytearray instance representing an integer literal in the
given base.  The literal can be preceded by '+' or '-' and be surrounded
by whitespace.  The base defaults to 10.  Valid bases are 0 and 2-36.
Base 0 means to interpret the base from the string as an integer literal.
 >>> int('0b100', base=0)
4

help(int) prints the above plus the int methods.

Functions coded in Python should not have the signature in the doc 
string because help() can get it from the function object itself.

 >>> def f(a, b=3, *, c='abc'):
	'''return (a + b) / len(c)

	a and b (default 3) are numbers.
	c must be a sequence (default 'abc').'''

	
 >>> help(f)
Help on function f in module __main__:

f(a, b=3, *, c='abc')
     return (a + b) / len(c)

     a and b (default 3) are numbers.
     c must be a sequence (default 'abc').

 >>>

-- 
Terry Jan Reedy