Personal tools
plone.api e documentazione: le linee guida del buon plonista

Scegliere la strada giusta può essere difficile a volte

Jan 15, 2015

plone.api e documentazione: le linee guida del buon plonista

Per non perdersi nel mare di possibilità implementative e scegliere sempre la strada giusta, basta seguire le linee guida che la comunità (finalmente) ci offre.

Si sa, il mondo è bello perché è vario, soprattutto nella programmazione: esistono mille modi diversi per risolvere un problema.

Un giorno Alice arrivò ad un bivio sulla strada e vide lo Stregatto sull'albero.
- "Che strada devo prendere?" chiese.
La risposta fu una domanda:
- "Dove vuoi andare?"
- "Non lo so", rispose Alice.
- "Allora, - disse lo Stregatto - non ha importanza".

Il lato positivo di questa libertà è che ognuno può implementare la soluzione come meglio crede.
Può capitare quindi che a seconda dell'umore, delle preferenze personali, o anche solo del tempo a disposizione (quante volte sarà capitato di avere tempi di sviluppo troppo serrati e scrivere del gran spaghetti code solo per poter concludere il lavoro) il risultato prodotto sia estremamente vario, ma funzioni comunque correttamente.

Il risvolto della medaglia, però, è che se si lavora in gruppo o in una comunità dove tutti possono leggere e attingere dal codice scritto da altri, ci si può trovare di fronte a codice incomprensibile: in questi casi il focus sul risultato finale non basta!
Se non si segue una certa linea di condotta, quello che si produce potrebbe risultare poco chiaro o troppo complicato e quindi generare confusione in chi non ha scritto direttamente quel codice. Soprattutto se chi legge non è un esperto e ha bisogno di capire qual'è la strada migliore da seguire.

Un esempio perfetto è lo sviluppo su Plone: esiste una grande varietà di componenti con cui interagire (registry, tool, utility, creazione e gestione di contenuti, utenti, workflow e security) e differenti modi per fare le stesse cose.

Per esempio, se si vuole accedere al catalogo ci sono almeno 3 modi diversi per farlo:

catalog = context.portal_catalog
from Products.CMFCore.utils import getToolByName
catalog = getToolByName(context, 'portal_catalog')
from zope.component import getMultiAdapter
tools
= getMultiAdapter((context, self.request), name=u'plone_tools')
catalog = tools.catalog()

Ognuno dei quali è più o meno corretto, ma tutti funzionano allo stesso modo. Sta però allo sviluppatore preoccuparsi che il catalogo sia effettivamente disponibile nel contesto corrente, e gestire eventuali eccezioni.

Per anni non c'è stata una documentazione "ufficiale" vera e propria, e la documentazione principale erano delle ricerche su google o l'analisi del codice sorgente.
Quindi, a seconda di chi aveva scritto un determinato pezzo di codice, poteva capitare di trovare una stessa soluzione implementata in modi diversi.

Negli ultimi anni, però, è stato svolto un grosso lavoro per colmare questi problemi con due principali soluzioni:

La documentazione di docs.plone.org, è un enorme lavoro fatto dalla comunità e soprattutto dal Documentation Team, che negli anni ha raccolto diverse documentazioni sparse nella rete (o nei vari singoli progetti, come per esempio Dexterity) e l'ha riunita, revisionata e riorganizzata in un unico punto che mira a diventare la guida ufficiale per gli sviluppatori.
Da ora in avanti quindi, se si vuole sapere qual'è il metodo corretto da seguire per fare una determinata cosa, si DEVE consultare docs.plone.org.

L'altro strumento utile per standardizzare lo sviluppo di software Plone, è l'utilizzo di plone.api.
Questo prodotto raccoglie una serie di utility che permettono di eseguire diverse operazioni con un'interfaccia più semplice e comune per tutti.
Per esempio, se si vuole utilizzare un qualsiasi tool, è previsto un unico metodo che permette di richiamare il tool desiderato, passandogli il nome corretto:

from plone import api
catalog = api.portal.get_tool(name='portal_catalog')

L'utilità di questo approccio, è che lo sviluppatore non deve preoccuparsi di importare moduli o librerie complicate (e spesso ricordarsi anche il percorso di importazione). Si importa plone.api e si usano i suoi metodi. La libreria si occupa anche della gestione di eventuali errori, quindi un ulteriore pensiero in meno.

Esistono utility per quasi tutte le operazioni base di Plone come le operazioni sui contenuti (crea/modifica/copia/sposta), operazioni di workflow, gestione di utenti e gruppi.

Personalmente, trovo queste due risorse molto utili nello sviluppo quotidiano.
Quando ho dei dubbi su come implementare dei componenti oppure ho bisogno di ricordarmi come funziona qualcosa, vado a verificare sulla documentazione, e per le operazioni più comuni utilizzo plone.api, per mantenere un certo standard.
Come riportato anche nel post sulla recente Plone Conference, si è iniziato a lavorare per integrare plone.api sempre di più nel core di Plone, in modo da rendere il core stesso più "standard" e soprattutto per dare un'esempio di good practices agli sviluppatori (le new entry in primis).

stregatto

A questo punto non avete più scuse per non iniziare a seguire questi chiari consigli.

comments powered by Disqus