Quali sono i vantaggi e i costi dell'annotazione dei commenti in PHP?

Ci sono alcuni problemi che vengono immediatamente in mente con le annotazioni dei commenti (e, in particolare, il formato di symfony2):

1. Confusione degli sviluppatori il codice che hai postato sembra esattamente come un commento alla documentazione di DocBlock. Mentre i commenti possono essere effettivamente intercambiabili tra i due meta-processori (ognuno che ignora ciò che non capiscono, o altri che usano un altro metodo per gestire con grazia le cose), gli sviluppatori possono o meno capire lo scopo di un determinato commento, specialmente se non hanno completamente familiarità con un sistema o l'altro. Inoltre, apre la porta a annotazioni confuse con documentazione, che può portare a qualcuno che rimuove ciò che pensano debba essere la documentazione, ma in realtà è "codice".
2. Potenziali conflitti tra i meta-processori A causa di quanto sopra, cosa succede se uno o l'altro meta-processore decide di essere più severo e non consente ciò che non riconosce? Ora il tuo processore si rompe in ogni punto immaginabile. Richiedendoti di dedicare tempo a ripulire e inevitabilmente a perdere qualcosa di valore nel processo (incluso il tempo e la documentazione o le annotazioni). Se si deve fare nei commenti (vedere i vantaggi), avrei almeno un indicatore diverso per distinguerlo dallo standard di documentazione (un buon esempio è i commenti SASS / Compass rispetto ai commenti CSS standard, i commenti CSS /**/ sono inviato al CSS compilato, mentre i commenti non-CSS // vengono mangiati dal compilatore, inoltre rende abbastanza facile distinguere tra i due, semplicemente guardando i primi due caratteri).
3. Code / comment line-blurring Nella programmazione in generale, il codice e i commenti dovrebbero essere separati. Il codice che deve essere eseguito non dovrebbe essere nei commenti, di solito per ovvi motivi (perché non viene eseguito). Inizierai quindi ad aprire la porta per fare altre cose all'interno dei commenti, potenzialmente spingendo fuori la possibilità di commentare effettivamente, o dover saltare attraverso altri cerchi per distinguere tra commenti in codice e commenti effettivi (che aumenteranno anche tempo / risorse di compilazione come il compilatore deve passare attraverso più commenti e determinare se sono significativi, invece di ignorarli tutti). Altre alternative che mi è capitato di vedere con un rapido sguardo ai commenti sull'annotazione di Symfony, includono lo stile di C # tra parentesi angolari attorno alle annotazioni, lo stile di decoratore di Python (in pratica ciò che symfony ha già, ma non racchiuso nei commenti), e probabilmente qualsiasi altro stile sarebbe superiore a farlo nei commenti. (O, per dirla in altro modo - Violare il "Non ho bisogno di guardare dentro i commenti per trovare l'origine dei bug "regola. )

Detto questo, fare qualcosa del genere non è privo di vantaggi.

1. Aggiunta di funzionalità che non sono disponibili in modo nativo nella lingua. Innanzitutto, questo è probabilmente il motivo per cui Symfony lo ha fatto in questo modo. PHP non ha decoratori / annotazioni e, pertanto, se si desidera tale funzionalità, è necessario trovare un modo per implementarla. Ancora di più, se lo vuoi e non vuoi che i tuoi utenti siano dipendenti dalle estensioni PHP (perché non possono sempre controllare quel livello del loro ambiente), devi trovare un modo per farlo internamente che non si rompa il compilatore PHP. I commenti sono la scelta più ovvia.

2. Fornisci un modo pulito per aggiungere varie funzionalità a segmenti specifici. Ho visto che le annotazioni / decoratori di più sono Python, ma probabilmente lo vedrai in un certo numero di altri lingue, se li usi. Ad esempio, CherryPy lo utilizza per esporre le funzioni come controller di pagine Web (ad esempio, è possibile accedere a una funzione con un decoratore specifico da un browser, allo stesso modo in cui si accede a determinate funzioni pubbliche nei controller PHP). Fondamentalmente forniscono una funzionalità di "estensione" a funzioni o classi, offrendo funzioni di utilità senza ingombrare il codice all'interno della funzione.

Sfortunatamente, non ne so abbastanza di Symfony per indicare gli altri con il formato di Symfony, ma c'è una lunga discussione sui pro / contro di questo in Thread di Hacker News a cui potresti essere interessato. Potresti essere interessato anche alla richiesta di modifica sul sito PHP per le annotazioni native.

Per me sembra una pessima pratica. Potresti ottenere lo stesso risultato con le meta-funzioni che restituiscono questo tipo di metadati sulle funzioni, come showAction__META () per l'esempio precedente, ma evita tutti i lati negativi - e ce ne sono molti. La necessità di leggere il codice sorgente solo per eseguirlo, cosa che semplifica le ottimizzazioni del compilatore / runtime in testa. Inoltre, non è direttamente testabile e richiede particolare attenzione quando si eseguono controlli di sintassi. È lo stesso stupido approccio di reinventare la ruota che prendono vari linguaggi di template, invece di usare PHP direttamente.

I costi possono essere trascurati efficacemente poiché questo è effettivamente tradotto in codice PHP e quindi memorizzato nella cache. Quindi, a meno che tu non cambi il codice spesso esegue solo il codice PHP (che in teoria potrebbe anche essere un codice più veloce di quello che avresti scritto a mano)

Il motivo è che questo è un modo carino e compatto di fornire queste informazioni al sistema, queste 5 linee richiederebbero, scritte in PHP alcune righe in più e si adattano bene alla cosa a cui è correlato.

Al rovescio della medaglia ogni astrazione porta costi e aggiunge una fonte per nuovi bug (cosa succede se il parser ha un bug o genera un codice bug?)