Best way to delimit variable elements of a path in code documentation?

Question

Often some element of a path is variable, but the path as a whole needs to be documented in some manner for later programmers. Especially when using *nix systems, almost any character is a valid symbol for the path. Given that, I would like to delimit the variable portions of my path to prevent misunderstanding, but in a way that also survives best across different display environments (especially the browser).

Methods I have seen include (example path in users home directory):

• /home/<username>/foo - needs special escape for web browser context
• /home/your_username/foo - unfortunately the variable element tends to be overlooked
• /home/{username}/foo
• /home/:username/foo

Which have you seen most often or had the most success with and why? If a double delimiter method (which seems to be the most common/successful), what lead your choice of delimiters?

Answer 1

By far I've seen (and used) /home/<username>/foo the most. Don't worry about special escapes for such comments because all of your code is going to need to have those characters escaped when displayed in a browser (you may very well have statements like echo "<table>"; in your code.

If escaping isn't possible for some reason, you can surround the term with spaces or underscores to prevent HTML parsing:

/home/<_username_>/foo

One added benefit of underscores is that some markups (like Markdown) will automatically make them italicized:

/home/<username>/foo

making them understandable in a text editor and nicely formatted in a webpage.

Answer 2

I'd say #1 is the clearest, and whats probably used most often. The < and > delimit it nicely, and clearly indicate something should be substituted there.