Il modo migliore per delimitare gli elementi variabili di un percorso nella documentazione del codice?

Naviga le tue risposte
2

Spesso alcuni elementi di un percorso sono variabili, ma il percorso nel suo insieme deve essere documentato in qualche modo per i programmatori successivi. Soprattutto quando si usano i sistemi * nix, quasi tutti i caratteri sono un simbolo valido per il percorso. Detto questo, vorrei delimitare le parti variabili del mio percorso per evitare malintesi, ma in un modo che sopravvive anche meglio in diversi ambienti di visualizzazione (in particolare il browser).

I metodi che ho visto includono (percorso di esempio nella home directory degli utenti):

  • / home / < nomeutente > / foo - richiede un'uscita speciale per il contesto del browser web
  • / home / your_username / foo - sfortunatamente l'elemento variabile tende a essere trascurato
  • / home / nomeutente {} / foo
  • / home /: username / foo

Che hai visto più spesso o con maggior successo e perché? Se un doppio metodo di delimitazione (che sembra essere il più comune / di successo), cosa ha portato alla scelta dei delimitatori?

    
posta Iiridayn 11.10.2010 - 23:52
fonte

2 risposte

2

Di gran lunga ho visto (e usato) /home/<username>/foo di più. Non preoccuparti delle fughe speciali per tali commenti perché tutto il tuo codice avrà bisogno di far sfuggire quei caratteri quando visualizzati in un browser (potresti benissimo avere dichiarazioni come echo "<table>"; nel tuo codice .

Se l'escaping non è possibile per qualche motivo, puoi circondare il termine con spazi o caratteri di sottolineatura per impedire l'analisi HTML:

/home/<_username_>/foo

Un ulteriore vantaggio dei caratteri di sottolineatura è che alcuni markup (come Markdown) li renderanno automaticamente in corsivo:

/ home / < nome utente > / foo

rendendoli comprensibili in un editor di testo e ben formattati in una pagina web.

    
risposta data 12.10.2010 - 00:09
fonte
2

Direi che il primo è il più chiaro e che probabilmente è il più usato. Il < e > delimitarla bene, e indicare chiaramente che qualcosa dovrebbe essere sostituito lì.

    
risposta data 12.10.2010 - 00:00
fonte

Leggi altre domande sui tag

come valutare il proprio progetto Richieste di funzionalità di tracciamento per componenti su piccola scala