How to refer to “True-like” and “False-like” when documenting a function?
.everyoneloves__top-leaderboard:empty,.everyoneloves__mid-leaderboard:empty,.everyoneloves__bot-mid-leaderboard:empty{ height:90px;width:728px;box-sizing:border-box;
}
Strongly related question.
When writing docstrings for my functions in python, I sometimes want to write something like this about argument specifications:
def foo(bar):
"""
Do some stuff.
bar : callable
must return True if XXX and False otherwise.
"""
if bar(...):
... # code goes here
However, this is not perfectly precise, because in this example bar could be returning any object that will be evaluated to True in the if-statement when the conditions XXX is fulfilled. Such a callable would be a perfectly valid argument to pass to foo.
How should I formulate my documentation to reflect that foo does not strictly requires bar's output to be a boolean?
My first move was to write something like "[...] must return an object that will be evaluated to True if ...", but I find it obfuscated.
python code-documentation
asked Nov 23 '18 at 19:28
AlexisAlexis
21110
|
show 1 more comment
Strongly related question.
When writing docstrings for my functions in python, I sometimes want to write something like this about argument specifications:
def foo(bar):
"""
Do some stuff.
bar : callable
must return True if XXX and False otherwise.
"""
if bar(...):
... # code goes here
However, this is not perfectly precise, because in this example bar could be returning any object that will be evaluated to True in the if-statement when the conditions XXX is fulfilled. Such a callable would be a perfectly valid argument to pass to foo.
How should I formulate my documentation to reflect that foo does not strictly requires bar's output to be a boolean?
My first move was to write something like "[...] must return an object that will be evaluated to True if ...", but I find it obfuscated.
python code-documentation
asked Nov 23 '18 at 19:28
AlexisAlexis
21110
6
A common way to refer to this is truthy and falsey. However, this is really no requirement at all, because any value returned bybar()will be either truthy or falsey.
– John Gordon
Nov 23 '18 at 19:31
1
How objects evaluate to true or false is often called "truthiness". Also, falsey is often spelled falsy.
– gilch
Nov 23 '18 at 19:35
@JohnGordon there are exceptions like numpy arrays. See this for further context.
– timgeb
Nov 23 '18 at 19:40
@timgeb Fair enough.
– John Gordon
Nov 23 '18 at 19:41
2
You can saybool(bar())must evaluate toTrueorFalse?
– Idlehands
Nov 23 '18 at 19:42
|
show 1 more comment
Strongly related question.
When writing docstrings for my functions in python, I sometimes want to write something like this about argument specifications:
def foo(bar):
"""
Do some stuff.
bar : callable
must return True if XXX and False otherwise.
"""
if bar(...):
... # code goes here
However, this is not perfectly precise, because in this example bar could be returning any object that will be evaluated to True in the if-statement when the conditions XXX is fulfilled. Such a callable would be a perfectly valid argument to pass to foo.
How should I formulate my documentation to reflect that foo does not strictly requires bar's output to be a boolean?
My first move was to write something like "[...] must return an object that will be evaluated to True if ...", but I find it obfuscated.
python code-documentation
asked Nov 23 '18 at 19:28
AlexisAlexis
21110
Strongly related question.
When writing docstrings for my functions in python, I sometimes want to write something like this about argument specifications:
def foo(bar):
"""
Do some stuff.
bar : callable
must return True if XXX and False otherwise.
"""
if bar(...):
... # code goes here
However, this is not perfectly precise, because in this example bar could be returning any object that will be evaluated to True in the if-statement when the conditions XXX is fulfilled. Such a callable would be a perfectly valid argument to pass to foo.
How should I formulate my documentation to reflect that foo does not strictly requires bar's output to be a boolean?
My first move was to write something like "[...] must return an object that will be evaluated to True if ...", but I find it obfuscated.
python code-documentation
python code-documentation
asked Nov 23 '18 at 19:28
AlexisAlexis
21110
asked Nov 23 '18 at 19:28
AlexisAlexis
21110
asked Nov 23 '18 at 19:28
AlexisAlexis
21110
asked Nov 23 '18 at 19:28
AlexisAlexis
21110
asked Nov 23 '18 at 19:28
AlexisAlexis
21110
21110
6
A common way to refer to this is truthy and falsey. However, this is really no requirement at all, because any value returned bybar()will be either truthy or falsey.
– John Gordon
Nov 23 '18 at 19:31
1
How objects evaluate to true or false is often called "truthiness". Also, falsey is often spelled falsy.
– gilch
Nov 23 '18 at 19:35
@JohnGordon there are exceptions like numpy arrays. See this for further context.
– timgeb
Nov 23 '18 at 19:40
@timgeb Fair enough.
– John Gordon
Nov 23 '18 at 19:41
2
You can saybool(bar())must evaluate toTrueorFalse?
– Idlehands
Nov 23 '18 at 19:42
|
show 1 more comment
6
A common way to refer to this is truthy and falsey. However, this is really no requirement at all, because any value returned bybar()will be either truthy or falsey.
– John Gordon
Nov 23 '18 at 19:31
1
How objects evaluate to true or false is often called "truthiness". Also, falsey is often spelled falsy.
– gilch
Nov 23 '18 at 19:35
@JohnGordon there are exceptions like numpy arrays. See this for further context.
– timgeb
Nov 23 '18 at 19:40
@timgeb Fair enough.
– John Gordon
Nov 23 '18 at 19:41
2
You can saybool(bar())must evaluate toTrueorFalse?
– Idlehands
Nov 23 '18 at 19:42
6
6
A common way to refer to this is truthy and falsey. However, this is really no requirement at all, because any value returned by
bar() will be either truthy or falsey.– John Gordon
Nov 23 '18 at 19:31
A common way to refer to this is truthy and falsey. However, this is really no requirement at all, because any value returned by
bar() will be either truthy or falsey.– John Gordon
Nov 23 '18 at 19:31
1
1
How objects evaluate to true or false is often called "truthiness". Also, falsey is often spelled falsy.
– gilch
Nov 23 '18 at 19:35
How objects evaluate to true or false is often called "truthiness". Also, falsey is often spelled falsy.
– gilch
Nov 23 '18 at 19:35
@JohnGordon there are exceptions like numpy arrays. See this for further context.
– timgeb
Nov 23 '18 at 19:40
@JohnGordon there are exceptions like numpy arrays. See this for further context.
– timgeb
Nov 23 '18 at 19:40
@timgeb Fair enough.
– John Gordon
Nov 23 '18 at 19:41
@timgeb Fair enough.
– John Gordon
Nov 23 '18 at 19:41
2
2
You can say
bool(bar()) must evaluate to True or False?– Idlehands
Nov 23 '18 at 19:42
You can say
bool(bar()) must evaluate to True or False?– Idlehands
Nov 23 '18 at 19:42
|
show 1 more comment
3 Answers
3
active
oldest
votes
This is a slang question! I've always wanted to answer one of these!
Ahem.
The term for something that evaluates to True when used in an if statement is "truthy". The term for something that evaluates to False when used in an if statement is "falsy" or "falsey". So, your documentation can be written like this:
def foo(bar):
"""
Do some stuff.
bar : callable
must return a truthy value iff XXX.
"""
if bar(...):
... # code goes here
"Iff" is more slang, this time from the mathematical world. It means "if and only if". These words are commonly used in programming contexts, so I expect most programmers will understand them; if not, truthy, falsy, falsey and iff all come up with their respective correct meanings when searched in a search engine.
answered Nov 23 '18 at 19:48
wizzwizz4wizzwizz4
3,88311738
@John Gordon: I did see your comment but I am glad to mark the question as solved.
– Alexis
Nov 23 '18 at 19:51
add a comment |
I'm not sure if there's a standard for this, but based on python's Truth Value Testing you would probably be safe writing something like
def foo(bar):
"""
Do some stuff.
bar : callable
when tested for truth value, return value should evaluate to True if and only if XXX.
"""
if bar(...):
... # code goes here
answered Nov 23 '18 at 19:43
andersourceandersource
52919
Verbose, but safe. Good in some contexts.
– wizzwizz4
Nov 23 '18 at 19:52
"evaluates to True (False)" would be also my anwer
– VPfB
Nov 23 '18 at 20:15
add a comment |
I would suggest that is is just fine to say "must return True if XXX and False otherwise." Because of duck typing, I read this the way you intend. Further, this seems to be standard in how the Python standard library documents things.
In fact, if you do strictly require the value to be True or False and use this language, I will have a very bad day tracking down this bug!
As others have said, "truthy" and "falsy" are fine, well-understood alternatives if you are still concerned.
answered Nov 23 '18 at 19:50
JETMJETM
2,21841731
add a comment |
Your Answer
StackExchange.ifUsing("editor", function () {
StackExchange.using("externalEditor", function () {
StackExchange.using("snippets", function () {
StackExchange.snippets.init();
});
});
}, "code-snippets");
StackExchange.ready(function() {
var channelOptions = {
tags: "".split(" "),
id: "1"
};
initTagRenderer("".split(" "), "".split(" "), channelOptions);
StackExchange.using("externalEditor", function() {
// Have to fire editor after snippets, if snippets enabled
if (StackExchange.settings.snippets.snippetsEnabled) {
StackExchange.using("snippets", function() {
createEditor();
});
}
else {
createEditor();
}
});
function createEditor() {
StackExchange.prepareEditor({
heartbeatType: 'answer',
autoActivateHeartbeat: false,
convertImagesToLinks: true,
noModals: true,
showLowRepImageUploadWarning: true,
reputationToPostImages: 10,
bindNavPrevention: true,
postfix: "",
imageUploader: {
brandingHtml: "Powered by u003ca class="icon-imgur-white" href="https://imgur.com/"u003eu003c/au003e",
contentPolicyHtml: "User contributions licensed under u003ca href="https://creativecommons.org/licenses/by-sa/3.0/"u003ecc by-sa 3.0 with attribution requiredu003c/au003e u003ca href="https://stackoverflow.com/legal/content-policy"u003e(content policy)u003c/au003e",
allowUrls: true
},
onDemand: true,
discardSelector: ".discard-answer"
,immediatelyShowMarkdownHelp:true
});
}
});
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
StackExchange.ready(
function () {
StackExchange.openid.initPostLogin('.new-post-login', 'https%3a%2f%2fstackoverflow.com%2fquestions%2f53452052%2fhow-to-refer-to-true-like-and-false-like-when-documenting-a-function%23new-answer', 'question_page');
}
);
Post as a guest
Required, but never shown
3 Answers
3
active
oldest
votes
3 Answers
3
active
oldest
votes
active
oldest
votes
active
oldest
votes
This is a slang question! I've always wanted to answer one of these!
Ahem.
The term for something that evaluates to True when used in an if statement is "truthy". The term for something that evaluates to False when used in an if statement is "falsy" or "falsey". So, your documentation can be written like this:
def foo(bar):
"""
Do some stuff.
bar : callable
must return a truthy value iff XXX.
"""
if bar(...):
... # code goes here
"Iff" is more slang, this time from the mathematical world. It means "if and only if". These words are commonly used in programming contexts, so I expect most programmers will understand them; if not, truthy, falsy, falsey and iff all come up with their respective correct meanings when searched in a search engine.
answered Nov 23 '18 at 19:48
wizzwizz4wizzwizz4
3,88311738
@John Gordon: I did see your comment but I am glad to mark the question as solved.
– Alexis
Nov 23 '18 at 19:51
add a comment |
This is a slang question! I've always wanted to answer one of these!
Ahem.
The term for something that evaluates to True when used in an if statement is "truthy". The term for something that evaluates to False when used in an if statement is "falsy" or "falsey". So, your documentation can be written like this:
def foo(bar):
"""
Do some stuff.
bar : callable
must return a truthy value iff XXX.
"""
if bar(...):
... # code goes here
"Iff" is more slang, this time from the mathematical world. It means "if and only if". These words are commonly used in programming contexts, so I expect most programmers will understand them; if not, truthy, falsy, falsey and iff all come up with their respective correct meanings when searched in a search engine.
answered Nov 23 '18 at 19:48
wizzwizz4wizzwizz4
3,88311738
@John Gordon: I did see your comment but I am glad to mark the question as solved.
– Alexis
Nov 23 '18 at 19:51
add a comment |
This is a slang question! I've always wanted to answer one of these!
Ahem.
The term for something that evaluates to True when used in an if statement is "truthy". The term for something that evaluates to False when used in an if statement is "falsy" or "falsey". So, your documentation can be written like this:
def foo(bar):
"""
Do some stuff.
bar : callable
must return a truthy value iff XXX.
"""
if bar(...):
... # code goes here
"Iff" is more slang, this time from the mathematical world. It means "if and only if". These words are commonly used in programming contexts, so I expect most programmers will understand them; if not, truthy, falsy, falsey and iff all come up with their respective correct meanings when searched in a search engine.
answered Nov 23 '18 at 19:48
wizzwizz4wizzwizz4
3,88311738
This is a slang question! I've always wanted to answer one of these!
Ahem.
The term for something that evaluates to True when used in an if statement is "truthy". The term for something that evaluates to False when used in an if statement is "falsy" or "falsey". So, your documentation can be written like this:
def foo(bar):
"""
Do some stuff.
bar : callable
must return a truthy value iff XXX.
"""
if bar(...):
... # code goes here
"Iff" is more slang, this time from the mathematical world. It means "if and only if". These words are commonly used in programming contexts, so I expect most programmers will understand them; if not, truthy, falsy, falsey and iff all come up with their respective correct meanings when searched in a search engine.
answered Nov 23 '18 at 19:48
wizzwizz4wizzwizz4
3,88311738
answered Nov 23 '18 at 19:48
wizzwizz4wizzwizz4
3,88311738
answered Nov 23 '18 at 19:48
wizzwizz4wizzwizz4
3,88311738
answered Nov 23 '18 at 19:48
wizzwizz4wizzwizz4
3,88311738
3,88311738
@John Gordon: I did see your comment but I am glad to mark the question as solved.
– Alexis
Nov 23 '18 at 19:51
add a comment |
@John Gordon: I did see your comment but I am glad to mark the question as solved.
– Alexis
Nov 23 '18 at 19:51
@John Gordon: I did see your comment but I am glad to mark the question as solved.
– Alexis
Nov 23 '18 at 19:51
@John Gordon: I did see your comment but I am glad to mark the question as solved.
– Alexis
Nov 23 '18 at 19:51
add a comment |
I'm not sure if there's a standard for this, but based on python's Truth Value Testing you would probably be safe writing something like
def foo(bar):
"""
Do some stuff.
bar : callable
when tested for truth value, return value should evaluate to True if and only if XXX.
"""
if bar(...):
... # code goes here
answered Nov 23 '18 at 19:43
andersourceandersource
52919
Verbose, but safe. Good in some contexts.
– wizzwizz4
Nov 23 '18 at 19:52
"evaluates to True (False)" would be also my anwer
– VPfB
Nov 23 '18 at 20:15
add a comment |
I'm not sure if there's a standard for this, but based on python's Truth Value Testing you would probably be safe writing something like
def foo(bar):
"""
Do some stuff.
bar : callable
when tested for truth value, return value should evaluate to True if and only if XXX.
"""
if bar(...):
... # code goes here
answered Nov 23 '18 at 19:43
andersourceandersource
52919
Verbose, but safe. Good in some contexts.
– wizzwizz4
Nov 23 '18 at 19:52
"evaluates to True (False)" would be also my anwer
– VPfB
Nov 23 '18 at 20:15
add a comment |
I'm not sure if there's a standard for this, but based on python's Truth Value Testing you would probably be safe writing something like
def foo(bar):
"""
Do some stuff.
bar : callable
when tested for truth value, return value should evaluate to True if and only if XXX.
"""
if bar(...):
... # code goes here
answered Nov 23 '18 at 19:43
andersourceandersource
52919
I'm not sure if there's a standard for this, but based on python's Truth Value Testing you would probably be safe writing something like
def foo(bar):
"""
Do some stuff.
bar : callable
when tested for truth value, return value should evaluate to True if and only if XXX.
"""
if bar(...):
... # code goes here
answered Nov 23 '18 at 19:43
andersourceandersource
52919
answered Nov 23 '18 at 19:43
andersourceandersource
52919
answered Nov 23 '18 at 19:43
andersourceandersource
52919
answered Nov 23 '18 at 19:43
andersourceandersource
52919
52919
Verbose, but safe. Good in some contexts.
– wizzwizz4
Nov 23 '18 at 19:52
"evaluates to True (False)" would be also my anwer
– VPfB
Nov 23 '18 at 20:15
add a comment |
Verbose, but safe. Good in some contexts.
– wizzwizz4
Nov 23 '18 at 19:52
"evaluates to True (False)" would be also my anwer
– VPfB
Nov 23 '18 at 20:15
Verbose, but safe. Good in some contexts.
– wizzwizz4
Nov 23 '18 at 19:52
Verbose, but safe. Good in some contexts.
– wizzwizz4
Nov 23 '18 at 19:52
"evaluates to True (False)" would be also my anwer
– VPfB
Nov 23 '18 at 20:15
"evaluates to True (False)" would be also my anwer
– VPfB
Nov 23 '18 at 20:15
add a comment |
I would suggest that is is just fine to say "must return True if XXX and False otherwise." Because of duck typing, I read this the way you intend. Further, this seems to be standard in how the Python standard library documents things.
In fact, if you do strictly require the value to be True or False and use this language, I will have a very bad day tracking down this bug!
As others have said, "truthy" and "falsy" are fine, well-understood alternatives if you are still concerned.
answered Nov 23 '18 at 19:50
JETMJETM
2,21841731
add a comment |
I would suggest that is is just fine to say "must return True if XXX and False otherwise." Because of duck typing, I read this the way you intend. Further, this seems to be standard in how the Python standard library documents things.
In fact, if you do strictly require the value to be True or False and use this language, I will have a very bad day tracking down this bug!
As others have said, "truthy" and "falsy" are fine, well-understood alternatives if you are still concerned.
answered Nov 23 '18 at 19:50
JETMJETM
2,21841731
add a comment |
I would suggest that is is just fine to say "must return True if XXX and False otherwise." Because of duck typing, I read this the way you intend. Further, this seems to be standard in how the Python standard library documents things.
In fact, if you do strictly require the value to be True or False and use this language, I will have a very bad day tracking down this bug!
As others have said, "truthy" and "falsy" are fine, well-understood alternatives if you are still concerned.
answered Nov 23 '18 at 19:50
JETMJETM
2,21841731
I would suggest that is is just fine to say "must return True if XXX and False otherwise." Because of duck typing, I read this the way you intend. Further, this seems to be standard in how the Python standard library documents things.
In fact, if you do strictly require the value to be True or False and use this language, I will have a very bad day tracking down this bug!
As others have said, "truthy" and "falsy" are fine, well-understood alternatives if you are still concerned.
answered Nov 23 '18 at 19:50
JETMJETM
2,21841731
answered Nov 23 '18 at 19:50
JETMJETM
2,21841731
answered Nov 23 '18 at 19:50
JETMJETM
2,21841731
answered Nov 23 '18 at 19:50
JETMJETM
2,21841731
2,21841731
add a comment |
add a comment |
Thanks for contributing an answer to Stack Overflow!
- Please be sure to answer the question. Provide details and share your research!
But avoid …
- Asking for help, clarification, or responding to other answers.
- Making statements based on opinion; back them up with references or personal experience.
To learn more, see our tips on writing great answers.
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
StackExchange.ready(
function () {
StackExchange.openid.initPostLogin('.new-post-login', 'https%3a%2f%2fstackoverflow.com%2fquestions%2f53452052%2fhow-to-refer-to-true-like-and-false-like-when-documenting-a-function%23new-answer', 'question_page');
}
);
Post as a guest
Required, but never shown
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
6
A common way to refer to this is truthy and falsey. However, this is really no requirement at all, because any value returned by
bar()will be either truthy or falsey.– John Gordon
Nov 23 '18 at 19:31
1
How objects evaluate to true or false is often called "truthiness". Also, falsey is often spelled falsy.
– gilch
Nov 23 '18 at 19:35
@JohnGordon there are exceptions like numpy arrays. See this for further context.
– timgeb
Nov 23 '18 at 19:40
@timgeb Fair enough.
– John Gordon
Nov 23 '18 at 19:41
2
You can say
bool(bar())must evaluate toTrueorFalse?– Idlehands
Nov 23 '18 at 19:42