Unlimited Plugins, WordPress themes, videos & courses! Unlimited asset downloads! From $16.50/m
Advertisement
  1. Code
  2. WordPress
Code

Programmare ad Oggetti con WordPress : Documentiamo il Plugin I

by
Difficulty:BeginnerLength:MediumLanguages:
This post is part of a series called Object-Oriented Programming in WordPress.
Object-Oriented Programming in WordPress: Building the Plugin II
Object-Oriented Programming in WordPress: Document The Plugin II

Italian (Italiano) translation by Piergiorgio Sansone (you can also view the original English article)

A questo punto della serie , abbiamo trattato molti argomenti, non solo abbiamo visto le basi della programmazione ad oggetti, ma abbiamo iniziato a costruire un plugin completamente funzionante.

Ma la sfida che dovremo affrontare con il lavoro fatto fino ad ora, è che non prevede nessuna documentazione circa il funzionamento del plugin. Richiamandoci all'articolo precedente, abbiamo fatto un una scelta ponderata posponendo quest'attività allo sviluppo.

A partire da questo articolo, vedremo come documentare il plugin WordPress e come farlo dato il nostro plugin .

Prima di procedere con il resto di questo articolo, vi esorto altamente a rivedere quanto abbiamo fatto sino ad ora. Come accennato in ogni articolo passato, ogni articolo si basa sul precedente articolo della serie.

  1. L'Introduzione
  2. Le Classi
  3. I Types
  4. Le Strutture di Controllo : Istruzioni Condizionali
  5. Le Strutture di Controllo : I Cicli
  6. Funzioni ed Attributi
  7. L'Ambito di applicazione (scopo)
  8. Costruire il Plugin I
  9. Costruire il Plugin II

Detto ciò, è il momento di volgere la nostra attenzione a come documentare il nostro plugin, ma prima di andare avanti a farlo, dobbiamo essere sicuri di aver capito appieno le norme in atto per documetare il nostro lavoro .

Quindi prima esprimere commenti che sono rilevanti per il nostro plugin, vedremo quello che tutti abbiamo bisogno di includere. Dopo di che, faremo esattamente questo per il nostro plugin nel prossimo articolo.

Gli standard di documentazione PHP WordPress

Per i principianti, il Codex WordPress fornisce un manuale specifico per gli standard di documentazione PHP WordPress. È possibile leggere gli standard nella loro interezza; Tuttavia, dobbiamo evidenziare le caratteristiche più importanti di quanto abbiamo intenzione di realizzare nel prossimo articolo.

Le cose principali che siamo interessati a documentare sono le seguenti:

  • Intestazioni dei file
  • Istruzioni require in linea
  • Definizioni di classe e funzione
  • Le proprietà della variabile o classe

Si tratta ovviamente di un insieme di articoli dal ritmo molto più lento rispetto ai due precedenti, ma data la quantità di lavoro che abbiamo esaminato finora, per alcuni lettori dovrebbe essere un gradito cambiamento di ritmo.

Quindi detto questo, incominciamo.

Intestazione dei File

Le intestazioni dei file sono univoche perchè sono un qualcosa che deve essere collocato in ogni file che compone un plugin (o un tema, ma che non è il focus di questa serie), ma non lo sono sempre.

Secondo il Codex:

Il blocco di intestazione del file PHPDoc è utilizzato per dare una panoramica di ciò che è contenuto nel file.

Il modello generale che useremo a partire nel prossimo articolo assomiglia a questo:

Si noti che nelle intestazioni dei file, non includiamo un periodo e ci sono due componenti della descrizione:

  1. Una breve descrizione
  2. Una lunga descrizione

Ogni volta che scrivo le descrizioni per i miei progetti specifici, provo a immaginare che la mia breve descrizione sia qualcosa che possa andare bene in cima al file README, che possa essere una sola, breve passo per il file, o che possa essere contenuta anche in qualcosa di più breve come un tweet.

La descrizione più lunga, naturalmente, possa essere facilmente più dettagliata a nostro piacere. In questo caso , esiste uno specifico formato che dobbiamo utilizzare per la descrizione lunga, ma questo va fuori dall'ambito di questo specifico articolo, di questo avremo un particolare esempio pratico nel prossimo articolo della serie.

Istruzioni require in linea

Occasionalmente, abbiamo la necessità di documentare il codice incluso all'interno di una fuzione o di una classe. Sono diverse da quelle definizioni di funzioni o le definizioni di variabili di classe.

Al contrario, pensare a questi come commenti inline per quando è necessario includere o richiedono una certa dipendenza. Si tratta generalmente uno script PHP separato sopra ogni altra cosa.

Ad esempio :

Si noti tuttavia che, secondo il Codex che questo non si limita solo alle chiamate di funzione quali require_once.

I file necessari o inclusi devono essere documentati con una breve descrizione del blocco PHPDoc . Per chiarezza questo è applicabile in linea facoltativamente, chiamando la funzione get_template_part() in caso di necessità.

Poiché il nostro plugin effettua chiamate dirette a script esterni, useremo un esempio pratico di questo nel prossimo articolo. La ragiore per la quale sto condividendo questo, non è solo per prepararci a ciò che verrà, ma anche per mostrarvi il formato appropriato di come sfruttarlo in qualsiasi modo possibile.

Definizione di classe e funzione :

Dato che il nostro plugin è nativamente object-oriented, e che abbiamo capito come documentare correttamente sia i nostri corsi che le nostre funzioni chiave. Non sto sostenendo che questi due aspetti siano la parte più importante nel documentare un plugin; Però credo tuttavia che tutta la documentazione sia importante.

Definizioni di Classe

Le definizioni di classe sono i commenti di codice che appaiono tra le intestazioni di file (di cui abbiamo discusso in precedenza) e il nome della classe.

Il formato chi si utilizza per documentare una classe è il seguente :

Se vi capita di guardare il Codex di WordPress per questo articolo, si noterà che essa fornisce maggiori informazioni di quanto ho incluso nella documentazione di cui sopra. Questo perché hanno incluso il contenuto le definizioni di classe e la funzione.

Invece, stiamo dividendo ognuno di esse in aree separate come riferimento futuro, in modo da cogliere nel prossimo articolo della serie.perché abbiamo documentato certe cose in un certo modo.

Definizioni di funzione

Simile alla definizione di classe, tale che ci possiamo aspettare di vedere quanto segue:

Avviso nel commento al codice sopra, c'è poca differenza per quello che abbiamo visto con la documentazione della classe.

Oltre a quanto c'è sopra, vediamo informazioni per:

  • variabili globali
  • parmetri
  • tipi restituiti

Ovviamente, questo è materiale non tipicamente utilizzato all'interno del contesto di una classe; Tuttavia è utilizzato all'interno del contesto di una funzione.

A tal fine, ecco come si può pensare di ognuno dei precedenti:

  • le variabili globali si riferiscono a quelle variabili che vengono utilizzate nell'ambito della funzione che sono globali per l'ambiente di WordPress. Sono incluse le variabili $post, $authordata ed altre di cui forniamo una lista qui
  • il tag @param si riferisce alle variabili che vengono accettate dalle funzioni. Ovviamente, questo include il tipo di variabile che accetta e una descrizione per quanto riguarda ciò che rappresenta la variabile.
  • Il tag @return viene descritto come il tipo di variabile che restituisce una funzione e una breve descrizione per quanto riguarda il tipo di dati che sono restituiti.

Piuttosto che dare un esempio concreto di questo, qui, faremo questo nel post riepilogativo con il codice che abbiamo scritto nel post precedente.

Variabile o proprietà di classe

Infine, proprietà delle variabili - o più comunemente conosciuto come proprietà della classe (che sono a volte chiamarle attributi), rappresentano i dati che si tengono all'interno della classe.

Ricordo da prima della nostra serie, abbiamo accennato che gli attributi sono come gli aggettivi che descrivono il sostantivo che rappresenta la classe.

Come si può vedere dall'articolo precedente, le proprietà della classe sono definite solo dopo il nome della classe e prima del costruttore (indipendentemente dal fatto se suo public o private).

Per documentare questi attributi, seguiamo il seguente modello:

Abbastanza facile da capire.

Alcuni potrebbero obiettare che l'uso di @access è frivolo poiché il modificatore di accesso della funzione che segue direttamente il commento spiega di che tipo di funzione si tratta.

Ma questo è il caso dove le differenze negli standard di documentazione WordPress differiscono da alcuni standard PHP (sia in atto che quelli che sono in corso di essere standardizzati).

Una parola sugli standard di PSR

In breve, PSR riporta le raccomandazioni standard di PHP come proposto dal gruppo di interoperabilità Framework PHP.

Potete leggere circa ognuno di questi standard qui:

  • PSR-0: Lo Standard di autocaricamento
  • PSR-1: Lo Standard del Codice Base
  • PSR-2: La Guida dello Stile del codice
  • PSR-3: L'interfaccia di registrazione
  • PSR-4: Autoloader

Cui PSR-5 in discussione in questo momento. Questi sono importanti da seguire per tutti gli sviluppatori di PHP indipendentemente dalla piattaforma o fondamento che stanno usando, ma penso anche che valga la pena notare che esistono differenze (e somiglianze) tra PSR e gli standard di WordPress.

Quale abbiamo scelto?

Questo è un punto di disaccordo, quindi quello che sto per dire è puramente soggettivo; Tuttavia, io sono di mentalità che, quando si lavora all'interno di WordPress, si dovrebbero seguire le convenzioni come proposto da WordPress.

Questo non vuol dire che non dovremmo fare uno sforzo per allineare maggiormente noi stessi con quello che sta facendo la più grande comunità PHP; Tuttavia, se stiamo scrivendo codice di WordPress per gli altri sviluppatori di WordPress, quindi questo è qualcosa su cui dovremmo essere principalmente concentrati.

Prossimi appuntamenti

Nel prossimo articolo, vedremo ed applicheremo i principi di cui abbiamo parlato sopra ma all'interno del contesto del nostro plugin.

Questo dovrebbe aiutarci a non solo costruire un plugin altamente conforme agli standard di codifica di WordPress, ma anche per gli standard di documentazione, in modo tale che noi, i nostri utenti e i nostri futuri collaboratori saremo in grado di seguire facilmente il flusso di controllo attraverso il progetto.

Nel frattempo, sentitevi liberi di lasciare eventuali domande e/o commenti nel feed qui sotto!

Advertisement
Advertisement
Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.