python function parameters, debugging, comments, etc.

[Terry Reedy]

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