How do you use `help` when write your code

[Chris Angelico]

On Mon, Jul 7, 2014 at 10:53 AM, Ben Finney <ben at benfinney.id.au> wrote:
> There are two common cases where ‘help(foo)’ is unable to help:
>
> * If ‘foo’ is a function written without using keyword-only args, but
>   needing to have a bunch of keyword arguments, the signature will often
>   be the uninformative ‘foo(*args, **kwargs)’. A docstring is crucial
>   here, but it's too often wrong or absent.
>
>   I look forward to more and more functions migrating to use
>   keyword-only arguments for these cases, so the function signature can
>   become much more informative in ‘help’.

Most common cause of this problem is when a function ought to have
functools.wraps but didn't.

if DEBUG:
    debug = print
else:
    @functools.wraps(print)
    def debug(*a, **kw): pass

Without wraps(), the non-debug-mode version of debug() is completely unhelpful.

There's another issue with help(), and that's when it's used on a
large class - it's not that it's unhelpful, it's more that the useful
information gets lost in the spam of a pile of dunder functions. Check
out help(1) for instance.

ChrisA