Question

While I am aware of the duck-typing concept of Python, I sometimes struggle with the type of arguments of functions, or the type of the return value of the function.

Now, if I wrote the function myself, I DO know the types. But what if somebody wants to use and call my functions, how is he/she expected to know the types?
I usually put type information in the function’s docstring (like: "...the id argument should be an integer..." and "... the function will return a (string, [integer]) tuple.")

But is looking up the information in the docstring (and putting it there, as a coder) really the way it is supposed to be done?

Edit: While the majority of answers seem to direct towards “yes, document!” I feel this is not always very easy for ‘complex’ types.
For example: how to describe concisely in a docstring that a function returns a list of tuples, with each tuple of the form (node_id, node_name, uptime_minutes) and that the elements are respectively a string, string and integer?
The docstring PEP documentation doesn’t give any guidelines on that.
I guess the counterargument will be that in that case classes should be used, but I find python very flexible because it allows passing around these things using lists and tuples, i.e. without classes.

Answer 1

This is how dynamic languages work. It is not always a good thing though, especially if the documentation is poor – anyone tried to use a poorly documented python framework? Sometimes you have to revert to reading the source.

Here are some strategies to avoid problems with duck typing:

• create a language for your problem domain
• this will help you to name stuff properly
• use types to represent concepts in your domain language
• name function parameters using the domain language vocabulary

Also, one of the most important points:

• keep data as local as possible!

There should only be a few well-defined and documented types being passed around. Anything else should be obvious by looking at the code: Don’t have weird parameter types coming from far away that you can’t figure out by looking in the vicinity of the code…

Related, (and also related to docstrings), there is a technique in python called doctests. Use that to document how your methods are expected to be used – and have nice unit test coverage at the same time!