Ho (finalmente) letto gli standard di codifica PEAR (php).qual è lo scopo degli asterischi extra nei commenti php?
Qual è lo scopo di commentare in questo modo:
/**
* Here is my comment
* I Wrote this in a haiku
* But why put the stars?
*/
Al contrario di questo:
/*
Here is a comment
No haiku or
anything special, but it still works!
*/
Il documento /** stuff */ viene indicato anche come DocBlock notazione.
E 'usato per documentare funzioni PHP, classi, ecc
/**
* A test function
*
* @param foo $bar
* @return baz
*/
function test(foo $bar) { return new baz; }
Alcuni editor fare buon uso di questo di svolgere la loro funzione Codice Insight, uno strumento molto potente che riduce il tempo che avete a spendere guardando le tue vecchie dichiarazioni di funzione. Aptana e Zend Studio hanno questa caratteristica, probabilmente anche altre.
È inoltre possibile utilizzarlo in combinazione con Reflection per eseguire una sorta di AOP, eseguendo l'ispezione in runtime di DocBlock sopra le dichiarazioni. Infatti, Doctrine lo usa per costruire un object attribute map per la loro implementazione "Active Record".
leggibilità.
Evidenzia chiaramente la sezione commentata per le persone che leggono il codice.
Questo è quello che pensavo ... Quindi è strettamente leggibile? Nessun altro vantaggio? –
se si sta utilizzando un editor che non mette in evidenza il contesto, aiuta a chiarire/identificare blocchi di commento più lunghi – Dave
Questo non è del tutto vero. TECNICAMENTE è una formalità usare l'asterisco dobule. Ma i sistemi di documentazione, come phpdoc, si basano su di esso. – dcbarans
Penso che sia principalmente per l'aspetto/la leggibilità. Immagina di avere una sezione di commenti molto lunga che si estende oltre una schermata. Quindi vedere quegli asterischi ti fa sapere che fa parte di un commento anche se non riesci a vedere l'inizio e la fine.
Sono d'accordo con Ajon e Quentin. Principalmente è leggibilità. Tuttavia, c'è ancora una cosa.
Esistono generatori di documentazione automatici (come doxygen).
Richiedono una particolare formattazione dei commenti per includere questi commenti nella documentazione. Credo che questo stile di commento sia usato esattamente per questo scopo (guarda la seguente pagina di documentazione doxygen - http://www.stack.nl/~dimitri/doxygen/docblocks.html)
Sì, l'ho trovato durante la ricerca di doxygen, quindi ho pensato che * ci fosse * un po 'di più –
Il doppio commento asterisco viene usato qualche volta da alcuni sistemi di documentazione. Il sistema di documentazione procede al blocco e cerca determinate parole chiave come @author o @var.
I singoli commenti asterisco vengono considerati come // commenti.
See PHPDoc http://www.phpdoc.org/docs/latest/guides/types.html
Se si utilizza l'ottimo testo libero Jedit per modificare il PHP mette in evidenza il codice in diversi colori per mostrare ciò che è un verbo, che è una variabile ecc
Se di commentare un blocco con/* ... */tutto all'interno del blocco diventa arancione, rendendo difficile la lettura del codice.
Se invece si commenta con/** ... * /, quindi cambia tutto nel blocco su un diverso set di colori che evidenzia ancora le diverse parti del codice, il che significa che il codice rimane molto leggibile.
PS. Se usi Blocco note o simili per modificare il tuo codice PHP, ti suggerisco caldamente di ottenere jEdit. Ti farà risparmiare un'enorme quantità di tempo e frustrazione. Cose come indicanti automaticamente l'inizio e la fine di {},() ecc.
Non capisco lo stretto voto. È una domanda legittima. C'è un vero motivo per commentare in questo modo. – bstpierre