Repository navigation
Clarify when to mark up numeric literals #1312
Description
The current devguide recommendations reads:
backquotes: ``text`` for code samples, variables, and literals.
Earlier, I've been corrected to use double backticks when marking up literals. Example PR remark:
Recently, I've seen other styles enforced:
Perhaps we need a clarification, possibly with good/bad examples?
Activity
Lincoln-developer commentedon Apr 26, 2024
Hey I would love to work on this, I see there a couple of discussions that have been going on with associated PRs, may be I could first look at those and for any other details I must know on this, @erlend-aasland kindly guide.
erlend-aasland commentedon Apr 29, 2024
Thanks! I believe we need to discuss this a little bit more before we can propose actual changes to the devguide. We need to agree what to put in the "good" section and what to put in the "bad" section. This implies more discussion needs to take place first.
Lincoln-developer commentedon Apr 29, 2024
Thanks for this response, let me look at another issue.
ezio-melotti commentedon May 3, 2024
My rule of thumb is that numbers should be marked as literals if they refer to values in the code (either actually written as literals or assigned/calculated/returned), e.g.:
0or1."42."math.piis defined as equal to3.14159."When the number doesn't directly refer to a value in the code, the literal markup can be omitted, e.g.:
mathmodule."Sometimes the difference is subtle though. For example, if you are suggesting the reader to multiply the result by
1000or talking about the operation done by a specific function, you might want to use a literal. However if the calculation already happened or if the focus is about the calculation itself and not the implementation that executes it, then you don't necessarily need to.In some ambiguous cases and especially with lists/tables, marking them as literals might also help the values stand out more (which might be desirable or not) or be easier to scan/compare. As always, use your best judgment in order to make the docs as clear and readable as possible.
FWIW the same applies to strings or other literals. For example, you can talk about "version 1.2.3" in general but "version
1.2.3" if it's returned by a function, assigned to a variable, or even used in a file likerequirements.txt, or you can say that "storeis the default action ofargparse.add_argument", and that "it will store the value passed from the CLI".