[Python-ideas] Boolean parameters guidelines

[Steven D'Aprano]

On Sun, May 08, 2016 at 01:58:35AM -0300, Joao S. O. Bueno wrote:
> On 7 May 2016 at 22:59, Steven D'Aprano <steve at pearwood.info> wrote:
> > So instead there are two separate functions, variance and
> > pvariance.
> 
> Which, to avoid copy and pasting code, would obviously each consist
> of a call do a _variance private function, passing the operation mode as a ...
> Boolean parameter.

You know, the standard library is open source, and the source code is 
available :-) You could easily check to see whether that is what it 
does:

https://hg.python.org/cpython/file/3.5/Lib/statistics.py

Ignoring docstrings, this is the current implementation of the two 
functions:

def variance(data, xbar=None):
    if iter(data) is data:
        data = list(data)
    n = len(data)
    if n < 2:
        raise StatisticsError('variance requires at least two data points')
    T, ss = _ss(data, xbar)
    return _convert(ss/(n-1), T)

def pvariance(data, mu=None):
    if iter(data) is data:
        data = list(data)
    n = len(data)
    if n < 1:
        raise StatisticsError('pvariance requires at least one data point')
    ss = _ss(data, mu)
    T, ss = _ss(data, mu)
    return _convert(ss/n, T)


So, no, it does not pass a hidden boolean argument. Virtually all the 
common code (apart from some trivial setup code) is already factored 
into private subfunctions, which I would have still done even if I had 
used a bool to set the mode.

Even if I did use a private bool arg, I think that exposing it in the 
public interface would have been the wrong choice. Conceptually, sample 
variance and population variance are related but distinct things. It 
makes for a better API to have two distinct functions rather than 
passing a flag to choose between them.

There are cases where using a bool to select a mode makes sense, which 
is why it is only a guideline, not a hard, unbending law that must 
always be obeyed, no exceptions. There may be cases where we choose to 
intentionally disregard the "No const bool args" rule, and that's 
okay, if we disregard it for good reasons. For example, I think that 
list.sort(reverse=True) is the right choice, in which case the other 
rules about using keyword arguments apply. But I think that we should 
start from a position of "No const bool args" being the preferred 
option.


-- 
Steve