Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question
add comment

2 Answers

up vote 2 down vote accepted

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.

share|improve this answer
add comment

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.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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