Share
In questa serie in due parti, stiamo dando un'occhiata alla costruzione di un caso per i commenti al codice. Nel primo articolo, abbiamo trattato il lato server dando un'occhiata a PHP. Nello specifico, abbiamo esaminato le convenzioni di PHPDoc e come usarle per documentare modelli, funzioni, linee e blocchi.
In questo articolo, daremo un'occhiata alle lingue lato client. Nello specifico, esamineremo HTML, CSS e JavaScript.
Sebbene non esistano necessariamente utilità di documentazione come phpDocumentor per tutti questi linguaggi, ci sono ancora strategie che possiamo impiegare per rendere più semplice il mantenimento dei nostri progetti (o per aiutare gli altri a contribuire ai nostri progetti).
Quando si tratta di lavorare con WordPress, temi e plugin varieranno nel tipo di file che includono. I temi di solito consistono in HTML e CSS e probabilmente in JavaScript, mentre i plugin potrebbe solo composto da PHP.
Nel primo articolo, abbiamo esaminato ciò che WordPress richiede per registrare i file modello con l'API, nonché i plugin richiesti. Prima di proseguire, ti consiglio di rivedere prima questo articolo in quanto copre le informazioni richieste mentre questo particolare articolo riguarderà solo le raccomandazioni per ciò che possiamo fare per migliorare i nostri commenti.
La maggior parte degli sviluppatori web è consapevole di come scrivere commenti nel contesto dell'HTML. Semplicemente, è una questione di prefisso del codice - sia esso una singola riga o un blocco - con . Quando si tratta di scrivere markup, non è terribilmente comune vedere i commenti oltre i condizionali che si possono trovare nel capo elemento del documento.
Esistono tecniche che possiamo usare per rendere il nostro codice più gestibile. Ciò è particolarmente utile quando si lavora con sistemi come WordPress perché alcuni elementi saranno distribuiti su più file.
Ad esempio, supponendo che tu stia creando un tema, probabilmente aprirai il tuo corpo elemento e un elemento contenitore nel header.php modello e quindi terminando gli elementi nel footer.php modello.
Questo è un esempio semplificato poiché è relativamente comune, ma il principio rimane vero attraverso gli altri file.
Detto questo, c'è una semplice strategia che possiamo usare per commentare il nostro codice:
Gli elementi HTML saranno in genere in una delle quattro forme:
Per ognuna di queste permutazioni, seguo le seguenti convenzioni:
Sopra, c'è un frammento di codice per un modulo che viene utilizzato per salvare le opzioni nel modulo di database di WordPress all'interno del Dashboard. In questo caso, normalmente lascerò un commento alla fine dell'elemento che indica lo scopo del modulo o qualche altro attributo, come l'attributo action.
Data questa strategia, l'esempio sopra può sembrare qualcosa del genere:
O:
La convenzione che scelgo di utilizzare consiste nell'utilizzare una barra rovesciata - in normale stile HTML - seguita dallo scopo della descrizione dell'elemento per farmi sapere che sto terminando l'elemento.
Anche se questo potrebbe non essere particolarmente utile con un singolo elemento isolato, ho trovato che sia utile con elementi nidificati e anche quando un elemento, come un contenitore, è diviso tra i file.
Nel caso in cui l'elemento abbia un ID, io uso il seguente commento:
Proprio come sopra, utilizzo una barra rovesciata seguita da un '#'che rappresenta un ID in CSS seguito dal nome del valore dell'attributo ID. Questo fammi sapere che sto terminando un elemento con l'ID specificato.
Ancora una volta, questo è molto utile quando un elemento esiste tra i file, ma è anche utile quando devi fare una ricerca globale nei file modello o nei file CSS.
Quando un elemento include solo una classe (o un insieme di classi), seguo una strategia simile come sopra: utilizzo una barra rovesciata, l'indicatore CSS per una classe e quindi la classe (o la prima classe) sull'elemento:
Abbastanza semplice.
Ma cosa succede quando l'elemento include sia un ID che una classe? Poiché gli ID sono unici e i nomi di classe non lo sono, per impostazione predefinita utilizzo sempre l'ID dell'elemento quando si termina il commento:
Ha senso, giusto? E il punto rimane ancora: questo rende facile sapere quale elemento sto finendo e lo rende facile trovarlo nel resto dei file di progetto.
JavaScript è simile a PHP in quanto supporta funzionalità di ordine superiore come funzioni (e prototipi se stai scrivendo vanilla JavaScript). Per questo motivo, è utile avere una convenzione con la quale documentiamo le nostre funzioni.
Ecco cosa: WordPress include jQuery per impostazione predefinita, quindi è comune che la maggior parte dei JavaScript specifici per WordPress sia scritta utilizzando una combinazione di JavaScript basato su jQuery e funzionalità basate su vanilla come le funzioni.
Le seguenti strategie si sono dimostrate utili nella scrittura di JavaScript in WordPress:
Innanzitutto, provo a denominare il file in base allo scopo che serve (come ad esempio Navigation.js o theme.js o admin.js).
In secondo luogo, fornirò anche una breve descrizione nella parte superiore di ciascun file utilizzando le convenzioni PHPDoc per la descrizione del file e per quanto tempo è stato parte del progetto:
/ ** * admin.options.js * * Gestisce i gestori di eventi per diversi elementi nella pagina delle opzioni di Dashboard. * * @since 1.0 * @version 3.2 * /
Per le funzioni, seguo una convenzione simile a quella precedente in quanto fornirò una breve descrizione della funzione, descriverò cosa accetta e cosa restituisce, oltre a quanto tempo è passato al progetto e alla versione corrente del file:
/ ** * Funzione di supporto attivata quando l'utente fa clic su "Fatto" o su "Invio" * quando si lavora per salvare le icone sociali. * * @param $ Un riferimento alla funzione jQuery * @param evt L'evento di origine di questo gestore * @returns Se l'utente ha premuto invio o annullato per salvare le proprie opzioni. * @since 1.0 * @version 1.2 * /
Questo in realtà non è altro che commenti di codice standard che la maggior parte degli sviluppatori usa spesso. C'è la variazione a riga singola, la variazione multilinea e lo scopo a cui servono: Cioè, semplicemente per descrivere cosa sta per accadere nel codice dopo il commento.
Accentsconagua
/ * * Se stiamo guardando l'icona del feed RSS, disabilita l'input * e collega l'utente alle opzioni globali per dove impostarlo. * / if ("! == sRssUrl) $ ('# social-icon-url') .val (sRssUrl) .attr ('disabled', 'disabled'); else $ ('# social-icon- url '). removeAttr (' disabled '); // end if C'è molto poco da aggiungere a questo che non ho trattato nel primo articolo, ma volevo menzionarlo qui per la revisione e per essere completo.
Sebbene non esista uno strumento di documentazione JavaScript ufficiale, jsDoc è diventato una delle utility più comuni per la documentazione del codice JavaScript.
Commentare i file CSS è decisamente molto più facile che lavorare con PHP o con il markup perché c'è davvero solo un modo per scrivere gli stili.
Cioè, tu definisci gli stili per un elemento usando un ID o una classe:
# no-comments font-size: 24px; altezza della linea: 36px; font-weight: bold; colore: # 444;
O:
.home .sticky: before display: blocco in linea; background: URL trasparente (images / sticky.png) no-repeat; larghezza: 58 px; altezza: 45px; contenuto: ""; posizione: assoluta; sopra: 26px; a sinistra: -9px;
In generale, non penso che sia necessario commentare gli stili, ma se ti trovi in una situazione in cui la parentesi quadra è fuori dallo schermo, potrebbe essere utile terminare lo stile con un commento come questo:
# no-comments font-size: 24px; altezza della linea: 36px; font-weight: bold; colore: # 444; /* #Non ci sono commenti */
O:
.home .sticky: before display: blocco in linea; background: URL trasparente (images / sticky.png) no-repeat; larghezza: 58 px; altezza: 45px; contenuto: ""; posizione: assoluta; sopra: 26px; a sinistra: -9px; / * .home .sticky: prima * /
Al momento, l'uso di linguaggi come LESS e Sass e i rispettivi preprocessori sta diventando sempre più popolare nello sviluppo web. Una delle caratteristiche più comuni di queste due lingue è che supportano le regole nidificate.
In questo caso, penso che ci sia un caso molto più forte per usare i commenti. Per esempio:
#header #slideshow # image-list list-style: none; fluttuare: a sinistra; margine: 0; larghezza: 100%; // # image-list // #slideshow // #header
In questo modo, sai quale elemento stai terminando indipendentemente da dove l'elemento inizia nell'IDE.
In questa serie, ho delineato il motivo per cui ritengo che i commenti sul codice dovrebbero essere qualcosa che tutti gli sviluppatori dovrebbero includere nel loro codice. In questo articolo, ho discusso le mie strategie su come commentare il mio markup, il mio JavaScript e i miei stili.
Anche se non sto dicendo la mia via è la solo modo di scrivere commenti - è solo un modo - credo che includere i commenti faccia un lungo cammino nel rendere un progetto più gestibile per te e per i tuoi pari, e penso che includerli nel tuo lavoro sia qualcosa che ogni sviluppatore dovrebbe puntare.
Speriamo che questa serie abbia fornito un caso per questo. Indipendentemente da ciò, mi piacerebbe sentire i vostri pensieri e suggerimenti nei commenti.
