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
--
https://mail.python.org/mailman/listinfo/python-list
