Descriptive boolean arguments

The problem with boolean method arguments is their missing context. What does true or false actually mean?

Problematic example

At this point the Module#constants(inherit) is meant to stand as example for the issue. The method expects a boolean value (inherit) as the argument. The default value is true:

File.constants.size
# => 49

All constants declared in the class (File) are returned. But what, if false is passed explicitely:

File.constants(false).size
# => 6

Obvisouly then less contants are returned. But why? The only way to find out is to take a look into the methods documentation (if it is accessible). That should not be neccessary.

Readable alternative

Quality code enables readers to access the implementation logic with the least necessary effort, in order to lower future costs (through debugging, onboarding new developers, … you name it). Vast documentation is certainly one option, but the problem with documentation is its tendency towards being legacy. Nevertheless the readability problem with boolean arguments is solved easily by the code itself:

File.constants(_including_ancestors = false).size
# => 6

Ah: it is about all constants, defined within File only. Gotcha.