¿La mejor manera de delimitar elementos variables de una ruta en la documentación del código?

Question

A menudo, algún elemento de una ruta es variable, pero la ruta en su conjunto debe documentarse de alguna manera para programadores posteriores. Especialmente cuando se usan sistemas *nix, casi cualquier carácter es un símbolo válido para la ruta. Dado eso, me gustaría delimitar las partes variables de mi camino para evitar malentendidos, pero de una manera que también sobrevive mejor en diferentes entornos de exhibición (especialmente el navegador).

Los métodos que he visto incluyen (ruta de ejemplo en los usuarios del directorio de inicio):

• /hogar/u003Cusername> /foo - necesita un escape especial para el contexto del navegador web
• /home/your_username/foo - desafortunadamente el elemento variable tiende a pasarse por alto
• /home/{nombre de usuario}/foo
• /Inicio/: nombre de usuario/foo

¿Con qué has visto con mayor frecuencia o tuvo el mayor éxito y por qué? Si un método de doble delimitador (que parece ser el más común/exitoso), ¿qué lleva a su elección de delimitadores?

Answer 1

Por mucho, he visto (y he usado) /home/<username>/foo la mayoría. No se preocupe por escapes especiales para tales comentarios porque Todo tu código necesitará que esos personajes escapen cuando se muestren en un navegador (muy bien puede tener declaraciones como echo "<table>"; en tu código.

Si escapar no es posible por alguna razón, puede rodear el término con espacios o subrayos para evitar el análisis de HTML:

/home/<_username_>/foo

Un beneficio adicional de los subrayadores es que algunos marcados (como Markdown) los harán automáticamente en cursiva:

/hogar/nombre de usuario>/foo

haciéndolos comprensibles en un editor de texto y bien formateados en una página web.

Answer 2

Yo diría que el n. ° 1 es el más claro, y lo que probablemente se usa con más frecuencia. El <y> delimitarlo bien, y indicar claramente que algo debe ser sustituido allí.