[Python-ideas] Boolean parameters guidelines

[Nick Coghlan]

On 8 May 2016 at 07:41, Serhiy Storchaka <storchaka at gmail.com> wrote:
> I propose to add following recommendations in PEP 8 or other documents:
>
> 1. It is preferable to pass boolean arguments as keyword arguments (if this
> is not the only argument).
>
> 2. It is preferable to declare boolean parameters as keyword-only
> parameters.
>
> What are you think about this?

With Steven's suggestion to also articulate the "Would two functions
be better?" question, I think it's a good idea.

Suggested points to note:

1. Do not use a boolean toggle to change the return type of a
function, define two different functions (e.g. os.walk vs os.fwalk,
os.getcwd vs os.getcwdb)
2. If the boolean toggle is expected to be constant for any given
call-site, consider defining two different functions (e.g.
statistics.variance vs statistics.pvariance)
3. If a boolean toggle is deemed appropriate, it is preferable to make
it keyword-only so call sites are always self-documenting
4. When calling a function that accepts a boolean toggle, it is
preferable to pass it by keyword to make the call more
self-documenting

The reason I think this is worth documenting is that it comes up
regularly in PEPs that require some associated API design, and these
are the rules of thumb we generally apply.

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia