python function parameters, debugging, comments, etc.
Terry Reedy
tjreedy at udel.edu
Tue Oct 1 19:56:41 EDT 2013
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
More information about the Python-list
mailing list