As a computer programmer, I comment my code. For example:
The following lines are dependent on "source 1" and "source 2". "Source 2" is a user login and password. Overall, the purpose is to retrieve an AWS token The ajax call to an AWS Gateway requires a token.
I double quote "source 1" and "source 2" to make it clear they are entities.
In US English, the accepted style is to always put commas or periods inside the closing quotation mark.
This is stated in The Chicago Manual of Style, 6.9 [paywall].
Periods and commas precede closing quotation marks, whether double or single …
He described what he heard as a “short, sharp shock.”
“Thus conscience does make cowards of us all,” she replied.
In UK English, the accepted style is generally—the specific rule is slightly more complex, as demonstrated in the University of Oxford Style Guide [PDF]—to put commas or periods inside the closing quotation mark if that punctuation is part of what's being quoted, otherwise to put them outside.
(It's a common misconception that UK English always has commas and periods go outside closing quotation marks. It's conditional.)
In UK English, therefore, the following is normal:
✔ Provide the password by typing 'password'.
Note the single quotation marks, which is standard in UK English.
But this poses a dilemma in conventional US English:
？ Provide the password by typing "password."
Is the period part of what you need to type, or is it merely punctuation that should not be typed?
Chicago address this specific situation in a couple of ways.
First of all, Chicago, 7.63 [paywall] says this:
When a word or term is not used functionally but is referred to as the word or term itself, it is either italicized or enclosed in quotation marks …
The term critical mass is more often used metaphorically than literally.
What is meant by neurobotics?
If following the style of using italics, the US English version of the sentence would be treated as follows:
Provide the password by typing password.
Since quotation marks are not used, and the period is not in italics, the meaning becomes clearer.
But it might not be clear if the period is actually in italics or not. While we assume that it is not part of the literal password, if it were, and it was in italics, it would be very difficult to distinguish—and using italics would not be a good option in such a specific situation.
To make such a presentation even clearer, Chicago does give a second option.
It says that in specific situations like this, where the US style of punctuation could cause confusion, it's acceptable to use the UK style of punctuation instead.
From Chicago, 6.9 [paywall]:
In an alternative system, sometimes called British style (as described in the New Oxford Style Manual …), single quotation marks are used, and only those punctuation points that appeared in the original material are included within the quotation marks; all others follow the closing quotation marks. (Exceptions to the rule are widespread …) Double quotation marks are reserved for quotations within quotations. This system … may be appropriate in works of textual criticism or in computer coding and other technical or scientific settings.
In short, where the US style of punctuation can cause confusion in technical documentation, where precision is essential, the UK style of punctuation can be substituted:
- ✔ Provide the password by typing 'password'.
- ✔ Provide the password by typing password.
However, what Chicago (and most style guides) would advise against doing (in the US) is using a hybrid of US and UK styles:
- ✘ Provide the password by typing "password".
Here, US-style double quotation marks are used with UK-style punctuation. While a few companies and people will do this, it's nonstandard and goes against conventional guidance. It at least has the appearance of being a mistake due to a lack of awareness of US-style punctuation.
In short, (1) rephrase the sentence so the quoted word or phrase is not positioned at the end of the sentence in the first place, (2) put it in italics, or (3) use UK styling.
Note that some in-house styles will use a different font face (such as courier) or style instead of italics in order to distinguish a word treated as a word from the body of the text.
As a programmer, you may appreciate that clarity is key in technical documentation. If you write
The password is "X7&t,dH," and should be entered on the login screen.
Readers will expect the password to be exactly what’s encompassed within the quotes, not to have to mentally parse the last character as a punctuation mark to be excluded.
If your code is
var greeting = "hello,"
what would you expect the value of greeting to be? Use the same convention for your comments; the people reading it are the same.
If you are using double-quotes to indicate the entities, then the full-stop (or comma, or question mark) goes outside the quotes; the punctuation is not part of the entity in quotes. This is the same rule as for using parentheses (brackets), rather than for quoting speech and text (wherein the punctuation is part of the speech or text).
While I would normally say that how you indicate the entities is entirely up to you, there is an important caveat — if you are writing this code for a Company, rather than for yourself, then check if they have a Style Guide defining this! For example, where I work, Table Names and Job Names are in ALL CAPS, without quotes, and use periods instead of spaces (which can look weird when it is followed by a full-stop).
The following lines are dependent on SOURCE.1 and SOURCE.2. SOURCE.2 is user login and password. Overall, the purpose is to retrieve an AWS token. The ajax call to an AWS Gateway requires a token.
Beyond that, go wild: use double-quotes, square brackets, braces (i.e. "curly brackets"), strokes or slashes, colons, bold, italic, hashes, or even just a different font (e.g. a monospaced serif font to make it look like a typewriter or old terminal console). Just make sure it is consistent throughout the documentation, so that the reader only has to decipher it once.
"Source 1"
[Source 1]
{Source 1}
//Source 1//
\Source 1\
:Source 1:
Source 1
Source 1
#Source 1#
Source 1
You might want to take a look at BNF, Backus-Naur form as a way to describe language elements and syntax. It's unambiguous and has been in use for a long time.You would use something like <source 1> and <source 2>.
This is a calling sequence definition from one of my bash scripts:
## kmprb ##
## Usage: kmprb [-ps <num>] [-1 [-rt]] ##
## [-b <num> | -B ] ##
## [ <file> ... ] ##
## -ps <num> override default print strategy ##
## with strategy <num> ##
## ##
## -1 call kmprb_one to print all 1 page jobs ##
## first ##
## ##
## -rt reformat text files before printing ##
## ##
## -b - break printing into batchs of no more ##
## than <num> sheets ##
## ##
## -B - same as -b, but get <num> interactively ##
## ##
## If -1 is specified, kmprb_one is called ##
## to allow the user to print all 1 page jobs ##
## first. -rt will be passed to kmprb_one to ##
## reformat text files with dprint ##
## ##
## If <file> ... is specified, then just those ##
## files (from the print queue) are offered for ##
## printing ##
## Otherwise, all files in the print queue are ##
## offered ##
