Share
Quando si tratta di scrivere codice, indipendentemente dalla lingua o dalla piattaforma utilizzata, noi sviluppatori tendiamo ad essere divisi su quanto o quanto poco dobbiamo commentare il nostro codice.
Da un lato, ci sono alcuni che credono che il codice dovrebbe essere auto-documentante. Cioè, dovrebbe essere scritto abbastanza chiaro in modo che non abbia bisogno di commenti.
D'altra parte, alcuni lo credono qualunque cosa dovrebbe essere commentato Cioè, dovrebbero esserci commenti per ogni classe, ogni funzione, ogni blocco e ogni riga.
Poi, naturalmente, ci sono quelli che cadono nel mezzo. In effetti, alcuni sviluppatori commentano solo le zone del loro codice che potrebbe essere fonte di confusione piuttosto che scegliere l'approccio tutto-o-niente delineato sopra.
Quando si tratta di scrivere codice per WordPress, abbiamo gli standard di codifica WordPress per fornire uno standard con cui dovremmo scrivere il nostro codice; tuttavia, non fornisce un valido argomento a favore o contro i commenti al codice.
In questa serie di articoli, fornirò un caso per codice commenti Nello specifico, spiegherò perché sono importanti, una raccomandazione su come farlo nel contesto dei file standard richiesti da WordPress (sia per i temi che per i plugin), e per come farlo per file HTML, fogli di stile e JavaScript File.
Prima di esaminare le varie parti che compongono un progetto WordPress, penso che sia importante discutere perché i commenti del codice siano importanti. Certo, molti di noi sanno che è per fornire una breve spiegazione di cosa sta succedendo con il codice, ma le implicazioni sono maggiori di quelle.
Nonostante il fatto che abbiamo standard con cui noi dovrebbero scrivendo il nostro codice basato su WordPress, alcuni sviluppatori li considerano come "consigli", figuriamoci quelli che non sono nemmeno a conoscenza di loro. Indipendentemente da quanto bene (o quanto male) scrivi il tuo codice, è ancora codice.
Dopotutto, se fosse facile da capire, non sarebbe chiamato codice (e non avremmo bisogno di commenti).
Non credo che dovremmo scrivere commenti sul codice solo con gli altri in mente. Penso che dovremmo scriverli da soli altrettanto. Quando rivedi il codice per la prima volta dopo che è trascorso un periodo di tempo significativo, è molto probabile che tu sia diventato un programmatore migliore, acquisito alcune nuove tecniche e / o spostato da come hai usato scrivere codice. Quindi, può essere difficile distinguere ciò che stavi cercando di fare.
E se per l'autore del codice è difficile da seguire, che speranza c'è per altri sviluppatori che stanno contribuendo, estendendo o migliorando il codice?
In definitiva, i commenti dovrebbero essere scritti sia per noi che per gli altri che potrebbero interagire con il nostro codice. Dovrebbero essere chiari, concisi e fornire tutte le informazioni necessarie che uno sviluppatore dovrebbe conoscere per poter lavorare con la sezione di codice fornita. Questo include tutte le informazioni che fanno riferimento al codice altro file (sia lato server o lato client), anche.
Detto questo, mi piacerebbe coprire alcune ragioni e strategie per commentare tutti i file che vanno nella creazione di un tema, un plugin o un'applicazione di WordPress.
A seconda del progetto, i file che è necessario includere variano. Ai fini di questo articolo, presumo che tu stia includendo file PHP, file HTML, fogli di stile e file JavaScript semplicemente per assicurarti che tutte le basi siano coperte. In questo articolo discuteremo il linguaggio lato server, cioè PHP, e nel prossimo articolo esamineremo le lingue lato client.
Quando si tratta di commentare i nostri file PHP, ci sono diversi requisiti che dobbiamo seguire:
Oltre a questo, sono richiesti davvero pochi commenti, quindi c'è ovviamente spazio per miglioramenti.
Quando si tratta di commentare il codice in PHP, c'è in realtà un modo consigliato di farlo - PHPDoc. Simile agli standard di codifica di WordPress, PHPDoc è uno standard per commentare (o documentare) il codice PHP. Fornisce un numero di convenzioni che sono applicabili a WordPress, ma un sottoinsieme di cui vedo usato regolarmente.
WordPress supporta due tipi di file modello:
Quando si tratta di documentare i file modello - indipendentemente dal tipo di modello - cerco sempre di fornire informazioni di intestazione che definiscono il nome del file, lo scopo del file, il pacchetto - o tema o plugin - di cui fa parte, e per quanto tempo è esistito nel progetto.
Per esempio:
/ ** * Nome modello: Progetti in vetrina * * Il modello utilizzato per l'area "Progetti in primo piano" della home page. Passa attraverso il tipo di post "Progetti in primo piano" e tira le tre voci più recenti. * * @package Project Theme * @since 1.0 * /
Come puoi vedere, ho fornito il necessario Nome modello per il file, ma ho anche dato una breve descrizione di cosa sta accadendo all'interno del file. Ho anche usato il @pacchetto e @da direttive per contribuire a dare ulteriore chiarezza.
Il @pacchetto direttiva, almeno nel contesto di WordPress, rappresenta il nome del tema o del plugin di cui questo particolare file è una parte.
Il @da direttiva indica per quanto tempo il modello è esistito nel progetto. Nel caso precedente, è ovviamente presente nel progetto sin dalla sua versione iniziale, ma non è affatto raro aggiungere file come tema o plugin, con il risultato che un numero di versione diverso appare come questo valore.
A causa della natura dei file di modello di base come l'indice, i modelli di pagina singola, degli archivi e così via, non è necessario definire un "Nome modello,"ma la descrizione, il pacchetto e le direttive sono ancora rilevanti.
Le funzioni di documentazione sono molto simili ai modelli di documentazione. Anche se non richiedono un tag specifico - come "Nome modello"- dovrebbero ancora includere una descrizione dello scopo della funzione e il @da direttiva.
Ci sono anche due direttive aggiuntive che una funzione può opzionalmente includere:
Accentsconagua
@param che descrive il tipo e la descrizione di un parametro che la funzione accetta@ritorno che descrive il tipo e la descrizione di ciò che la funzione restituisceNaturalmente, le funzioni non accettano sempre i parametri e le funzioni non sempre restituiscono valori, quindi la ragione per cui queste due direttive sono facoltative.
Supponendo che tu abbia una funzione che supporta entrambe le direttive precedenti, ecco come dovresti aspettarti che la documentazione appaia:
/ ** * Inserisce a livello di codice una pagina nel database. * * @param $ title Il titolo della pagina. La variante minuscola funge anche da slug di pagina. * @param $ nome_modello Il nome del file modello situato nella directory 'templates'. * @return L'ID della pagina che è stata creata * @since 1.0 * /
Per ulteriori informazioni su ciascuna di queste direttive, è possibile rivedere i tag PHPDoc; tuttavia, puoi vedere quanto utile possa essere utile per lavorare su un tema o un plug-in: ci vuole un bel po 'di fatica per dover discernere ciò che tu o un altro sviluppatore stavi cercando di ottenere con una determinata funzione.
Sebbene ci siano poche raccomandazioni o standard effettivi per la documentazione di blocchi di codice, credo ancora che sia utile soprattutto quando si tratta di loop o condizioni condizionali più complicati.
Tutto ciò può essere dimostrato nel seguente esempio: Supponiamo che sia necessario impostare una query personalizzata per eseguire il loop dei metadati dei post e quindi eliminarli se viene trovata una determinata chiave e / o valore. Ciò richiederebbe i seguenti passaggi:
Questo esempio documenterà sia le singole linee che i condizionali. Per prima cosa, diamo un'occhiata al codice sorgente e poi esamineremo cosa sta facendo subito dopo:
// Imposta gli argomenti per recuperare tutti i post pubblicati $ arguments = array ('post_type' => 'post', 'post_status' => 'publish', 'numberposts' => -1); // Crea un'istanza della query $ posts_query = new WP_Query ($ arguments); // Se vengono trovati messaggi, passateli ciclicamente se ($ posts_query-> have_posts ()) while ($ posts_query-> have_posts ()) $ posts_query-> the_post (); / * * Per ogni pezzo di post meta trovato, memorizza i suoi valori in * the $ meta_key e $ meta_value per noi da controllare. * / foreach (get_post_meta (get_the_ID ()) come $ meta_key => $ meta_value) / * * Potrebbero esserci più meta chiavi (come tweet_url_0, tweet_url_1) * quindi è necessario verificare se il 'tweet_url' si trova nel * $ meta_key. * * Se è così, possiamo cancellare i meta dati del post * / if (false! = Strstr ($ meta_key, 'tweet_url')) delete_post_meta (get_the_ID (), $ meta_key); // end if // end foreach // end while // end if // Reimposta la query personalizzata in modo da non interferire con altre query o The Loop wp_reset_postdata (); Idealmente, i commenti sopra dovrebbero fornire tutta la documentazione e le spiegazioni necessarie per capire cosa sta succedendo nel codice. Forse l'unica cosa che può essere richiesta è la comprensione del strstr funzione.
Il punto chiave che sto cercando di fare con il codice sopra è che se stiamo documentando singole linee, allora è meglio attenersi alla convenzione a linea singola - cioè, // - ma se stiamo scrivendo un commento che si estende su più righe, è sempre meglio usare il commento multilinea - cioè, il / * * /.
Si noti inoltre che non ogni singola riga ha essere commentato Piuttosto, blocchi (o blocchi) di codice possono essere spiegati in un commento multilinea che documenta cosa sta per succedere nel seguente codice sorgente.
Naturalmente, questo non è uno standard o un modo preferito per fare le cose. È solo una strategia che ho visto usato, che apprezzo e che uso da solo.
Se finisci seguendo le convenzioni stabilite in PHPDoc, allora ci sono un certo numero di utility che possono generare pagine di documentazione per il tuo lavoro. Probabilmente, lo strumento più popolare è phpDocumentor.
In breve, phpDocumentor è un'utilità che passerà attraverso il codice sorgente alla ricerca di commenti di codice PHPDoc formattati correttamente (in particolare su classi e funzioni) e genererà quindi una serie di pagine in stile che catturano le informazioni nei commenti.
Ciò rende la spedizione la documentazione orientata agli sviluppatori con la tua applicazione un gioco da ragazzi.
In questo articolo ho spiegato perché credo che i commenti sul codice dovrebbero essere qualcosa che tutti gli sviluppatori dovrebbero includere nel loro codice. Sebbene il Codice WordPress definisca un insieme di base di commenti richiesti per il nostro lavoro e / o per interfacciarsi con l'applicazione WordPress, c'è ovviamente più lavoro che possiamo fare per migliorare la chiarezza del nostro codice.
Il fatto è che ne abbiamo coperto solo la metà. Quindi, nel prossimo articolo, daremo un'occhiata alla documentazione di markup, JavaScript e stili.
@pacchetto Direttiva@da Direttivastrstr