2

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?

2

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.

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.