30

When I'm writing answers that include code snippets, I often need to differentiate between text that is required and text that needs to be replaced. With a command like cp source dest I have seen a number of different ways that users have attempted to communicate this, such as:

Is there a recommended method?

8
  • 4
    The less lazy answer is usually preferred, all other things equal ;)
    – cs95
    Jun 5, 2019 at 23:29
  • 5
    Both the keywords and angle brackets seem decent and common enough. I don't think there is some sort of official method here.
    – VLAZ
    Jun 6, 2019 at 6:52
  • 27
    Angle brackets have a disadvantage that without an explicit statement, it's not always clear whether the angle brackets are supposed to be removed. A new programmer may not immediately realize that the angle brackets should be removed in cp <file1> <file2> and kept in #include <headername.h>. Jun 6, 2019 at 8:07
  • 1
    I usually use italicised descriptive names. More obvious if they're mixed in with some actual parameters. And if I could work out how to do it in a comment I'd give an example.
    – spodger
    Jun 6, 2019 at 8:21
  • 8
    foo and bar are always handy. Jun 6, 2019 at 8:29
  • @HansPassant at that point, they are as obvious as calling your index in your for loop i. :)
    – aloisdg
    Jun 6, 2019 at 12:14
  • It's not code snippets, rather command line. Those are already have documentation somewhere, stick to documentation syntax at best: cp foo.txt bar.txt. Disregards, this situation is very similar to pseudo-code, sometimes it's good, sometimes it's bad. The best is to use documentation standards, whatever they are. Imho both methods you describe are.. bad. Beginners may try cp C:\A/to/source/FILE1.TXT /C:\B/to/destination/FILE2.TXT or cp <C:\A\FILE1.TXT> <C:\B\FILE2.TXT>. If you introduce your pseudo-syntax to simplify things, then also explain it.
    – Sinatr
    Jun 6, 2019 at 12:20
  • @Sinatr Shell commands are code.
    – jpmc26
    Jun 6, 2019 at 17:00

3 Answers 3

23

The intuitive way is the most coherent method related to your language. It should be obvious for people willing to answer you. A method related to your language is great because they are already familiar with the technology.

A line with field to be replaced is a template. You can use the templating synthax of your language if there is one. If your technology use <% name %> or {name} for templating, follow this convention.

Another idea, would be to follow your technology's documentation. For example in your case man cp use cp [OPTION]... [-T] SOURCE DEST, so a good option would have to write cp FILE1 FILE2.

We are not talking about what is the best. We want to communicate the meaning to readers. No need to change. If this is good enough for the language, it is enough for your question.

2
  • 10
    We want to communicate the meaning to readers. This is the most important part. Pick the option that you feel has the least potential for confusion in that specific context for the broadest group of readers and go with it. Conventions can help with this (e.g. the man page part) but there is no universal recommendation for all cases beyond this. Jun 6, 2019 at 8:44
  • 4
    Tangentially, some askers will use their own formatting for text that should be replaced in the body of their question - I generally find myself re-using that same formatting to minimize confusion both amongst the askers as well as future readers. While it might seem good on paper, a standardized convention for this may be more confusing than it's worth, especially for newer contributors.
    – esqew
    Jun 6, 2019 at 15:38
13

Regardless of the convention you use for the placeholder identifier text, you may want to also consider italicizing the substitutions for additional clarity. Unfortunately, this is only possible if you manually write out the HTML for the code block yourself, which can be inconvenient.

Don't worry, this won't break code syntax highlighting, as long as your placeholder is valid syntax.

cp -iL $SOURCE $DESTINATION # copy the thing
<pre><code>cp -iL <i>$SOURCE</i> <i>$DESTINATION</i> # copy the thing</code></pre>
class YourClass extends YourSuper { ... }
<pre><code>class <i>YourClass</i> extends <i>YourSuper</i> { ... }</code></pre>

This might not stand out in all fonts, but if you're using a monospace font with a proper distinct italic character style (rather than generated pseudo-italic or oblique style), it can make the substitutions much clearer.

2
  • I see your syntax highlighting example, which is great; is the issue just that there is no syntax highlighting built in to StackOverflow for bash? Even when I wrap the line in <pre><code> no highlighting appears.
    – enharmonic
    Jun 6, 2019 at 19:11
  • @enharmonic Google Code Prettify claims to support Bash, but it seems very limited. Modified the example to use a comment, which does seem to be highlighted correctly.
    – Jeremy
    Jun 6, 2019 at 19:17
6

The difficulties of all sorts of special characters and "(custom) template syntax" have already been pointed out. Sophisticated formatting with HTML may be one option that is applicable in some cases, when bold and italic text makes it easier to spot the text that has to be replaced. But in many cases it can probably help to explicitly say what has to be replaced.

For example:

If your header is called example.h, then you can include it with

#include <example.h>

Another example:

If you want to create a git tag named v1.4, with a comment like this is my version 1.4, then you can type

git tag -a v1.4 -m 'this is my version 1.4'

(Git is one example where this is notoriously difficult: There are names that are used by convention, but whenever something like origin, master or upstream appears in a command, it's important to know that these might as well be called differently)

Re-stating what exactly has to be replaced could be done in addition to the formatting. Additionally, it allows to unpack any "template syntax" that has been used with an example:

You can copy a source file to a destination file with

cp <source> <destination>

For example, when your source file is path/to/source/file and it should be copied to /path/to/destination/file, then this can be done with

cp path/to/source/file /path/to/destination/file

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .