Il lavoro di sviluppatore oggi, a causa dei tempi molto ristretti, della dinamicità degli strumenti e della loro varietà, non concede molto spazio per soffermarsi sulla documentazione dei prodotti che si utilizzano quotidianamente, siano essi pacchetti completi o librerie di supporto. Nella sua “documentazione per sviluppatori telepatici”, Gojko Adzic mette in evidenza il fatto che spesso non si possono né redigere né leggere estese documentazioni per i prodotti rivolti agli sviluppatori.

L'implementazione della reflection nei principali tool di programmazione, sembra aver donato agli sviluppatori una specie di potere telepatico, che consiste nel conoscere ogni oggetto che si vuole utilizzare, senza dover leggere un manuale che lo descriva. Così gli autori delle API, non devono solo coprire tutte le richieste funzionalità, ma devono anche preoccuparsi che risultino intuitive da utilizzare.

Gojko Adzic fornisce a tal proposito, una serie di suggerimenti e comincia ad esporre perplessità sull'utilità dei commenti troppo lunghi, in quanto molti tool di reflection mostrano solo le prime linee di commenti ai metodi, mentre altri visualizzano solo il metodo e i suoi parametri. Dato che un commento più lungo di una linea di testo probabilmente non sarà letto dalla maggior parte degli sviluppatori, lo sforzo di inserire commenti nel codice, dovrebbe essere impiegato per rendere le API più intuitive. E' una buona idea esprimere i concetti base delle proprie API nell'esempio Hello World, dato che questo viene in genere utilizzato come un modo veloce per partire.

Un'altra indicazione riguarda l'utilizzo delle eccezioni come una sorta di documentazione: se una precondizione non risulta soddisfatta, un generico messaggio di “operazione non supportanta” non è di molto aiuto, e quindi si potrebbe lanciare un'eccezione con l'accortezza di spiegare perchè si è verificata, e dando informazioni su come poterla evitare, magari accompagnandola con un collegamento a maggiori informazioni on line.

Un'API risulta essere di buona qualità quando l'utilizzo corretto di essa richiede meno codice rispetto ad un utilizzo scorretto. Sarebbe utile per gli sviluppatori di API prendere in prestito, dai progettisti di interfacce utente, il principio secondo cui le funzioni di base sono prontamente disponibili, mentre le caratteristiche più potenti, sono accessibili mediante un bottone o sono raggruppate sotto funzionalità Avanzate. Le API dovrebbero essere sottoposte ad un test di utilizzo da parte di persone esterne al team; dato che esse vengono sviluppate per astrarre l'utente dalla complessità del sistema sottostante e semplificarne l'utilizzo, verificare come queste vengono utilizzate senza avere la conoscenza dei dettagli, darà una percezione più precisa della qualità del proprio lavoro, e sancirà se il sistema può essere così utilizzato.

Per finire, Gojko Adzic prende ad esempio il framework Swing, che ritiene incredibilmente flessibile, ma che a suo parere, non è riuscito a raggiungere una parte significativa di mercato, a causa delle basse prestazioni percepite dagli utenti. Il problema viene individuato nel modello di threading usato impropriamente, a proposito del quale si può consultare quanto già pubblicato sul nostro sito. Swing utilizza un singolo thread di background per trattare tutti gli aggiornamenti della GUI e per default gli sviluppatori tendono ad utilizzare quel thread per il proprio flusso di lavoro, che congela la GUI e mostra lo schermo grigio. Benché il modello di threading fosse documentato chiaramente, molti sviluppatori lo hanno alla fine ignorato, e anche a voler sottolineare le responsabilità dell'utilizzo scorretto dell'API, resta il fatto che alla fine il danno è stato inferto al prodotto. Si possono evitare problemi simili con i propri prodotti, ponendo attenzione nel rendere le proprie API più facili da utilizzare.