Lo sforzo dedicato alla documentazione del software non deve quindi essere visto come un’attività costosa e noiosa, alla quale associare la minima priorità, poichè i benefici di una buona documentazione sono sempre tangibili.
Non a caso, molti fattori di qualità sono direttamente o indirettamente influenzati in maniera positiva dalla presenza di documentazione.
In particolare, la tracciabilità della documentazione nel codice o nell’architettura riduce notevolmente lo sforzo legato al processo di comprensione del software.
I documenti sono prodotti usando differenti sistemi e computers.
Standard di inter-scambio consentono che documenti elettronici siano scambiati, inviati per e-mail, …
Necessità di archiviazione. La vita di un sistema di word processing può essere più breve di quella del software che si sta documentando.
XML si sta ergendo quale standard per lo scambio di documenti.
Oltre a tutta la documentazione a corredo di tutte le fasi alte del ciclo di vista del software, è fondamentale anche la documentazione interna del codice.
Una corretta e completa documentazione del software facilita e supporta molte fasi del ciclo di vita:
L’utilizzo di standard di documentazione noti presenta diversi vantaggi:
La documentazione interna al codice dovrebbe essere:
Tra gli innumerevoli standard di documentazione esistenti, verrà presentato Javadoc.
Come tool generante, oltre a javadoc, verranno mostrate le potenzialità di Doxygen.
@author name-text
@deprecated deprecated-text
{@code text}
{@docRoot}
@exception class-name description
{@inheritDoc}
{@link package.class#member label}
{@linkplain package.class#member label}
{@literal text}
@param parameter-name description
@return description
@see reference
@serial field-description | include | exclude
@serialField field-name field-type field-description
@serialData data-description
@since since-text
@throws class-name description
{@value package.class#field}
@version version-text
La documentazione di riferimento del “linguaggio” javadoc e dei modi di utilizzo del tool corrispondente è disponibile all’indirizzo: http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#tags
Esistono strumenti in grado di valutare la completezza della documentazione
Checkdoc della Sun: http://java.sun.com/j2se/javadoc/doccheck/
Il tool javadoc, richiamabile da linea di comando, genera un insieme di file in puro HTML (con l’utilizzo di frames), altamente navigabili.
Non è prevista, viceversa, la generazione di un unico documento, che possa costituire lo scheletro di un manuale utente.
Sistema di documentazione utilizzabile per programmi scritti in C++, C, Java, ed altri.
Genera documentazione in HTML e anche un manuale di riferimento completo in RTF (MS-Word), PostScript, PDF, chm o man Unix, direttamente a partire dalle informazioni reperibili nel codice sorgente.
Doxygen estrae i commenti scritti in formato simile a quello di Javascript e inoltre la struttura dei costrutti principali ricavabili dall’analisi statica del codice, comprese associazioni, ereditarietà, …
Doxygen genera automaticamente alcuni diagrammi, tra cui grafi delle dipendenze, diagrammi di ereditarietà, diagrammi di collaborazione ed altro, secondo il formato DOT.
http://www.research.att.com/sw/tools/graphviz/
Per Naming Guidelines si intende un insieme di regole da seguire nella scelta dei nomi di variabile.
Si definiscono Pascal Cased i nomi che hanno le iniziali maiuscole (es. RegisterClientScriptCallBack).
Sono Camel Cased i nomi che hanno l’iniziale della prima parola minuscola e le iniziali delle rimanenti parole maiuscole (es. httpContext).
Naming convention nella quale ogni nome di variabile dipende dal suo tipo e dal suo scopo;
Proposta dall’ungherese Charles Simonyi.
Si applica di solito ai nomi delle variabili.
Ogni nome di variabile inizia con un prefisso costituito da una o più lettere minuscole in modo da formare un codice mnemonico per il tipo o lo scopo di questa variabile. Il primo carattere del nome assegnato è in maiuscolo per separarlo visivamente dal prefisso, coerentemente con lo stile CamelCase.
È applicabile a qualsiasi linguaggio di programmazione;
Diventa fondamentale in tutti quei linguaggi, come ad esempio alcuni degli attuali linguaggi di scripting, nei quali non siano previsti controlli a tempo di compilazione sulla coerenza dei tipi delle variabili.
Non è strettamente necessaria in nessun linguaggio compilato.
Potrebbe essere utile al programmatore come elemento di tracciabilità della documentazione
Aumenta la dimensione del codice e il tempo necessario a scriverlo.
Può portare a problemi di errata interpretazione degli acronimi dei tipi per le classi e i tipi definiti dall’utente.
Sono in corso dibattiti sull’utilità relativa al mantenimento della notazione nei moderni linguaggi object oriented.
Microsoft, nelle MSDN, ad esempio, inizia a sconsigliarne l’utilizzo, precedentemente consigliato.
Tutti i tipi e membri pubblici devono essere Pascal Cased
class MyClass
public string ClassName
public string GetClassName()
I parametri devono essere Camel Cased
public void LoadData(int objectId) { ... }
Gli acronimi sono gestiti All Cased se di 2 caratteri, Pascal Cased altrimenti
public int ID; public string Html;
Usare i nomi al plurale per metodi e proprietà che ritornano collections o array
public MemberCollection GetMembers(); public Member GetMember()
Utilizzare il prefisso “Is”, “Has” o “Can” nel caso di metodi che restituiscono un boolean
public boolean IsMemberOfTeam();
public boolean HasRows();
public boolean CanWrite();
Non usare prefissi per i nomi delle classi
// errato public class CPersona {...}
// corretto public class Persona {...}
Usare il prefisso “I” per i nomi delle interfacce, distinguendole dalle classi
public interface IPersona {...}
Utilizzare un nome composto per le classi derivate, aggiungendo come suffisso il nome, o parte del nome, della classe base
public class PersoneCollection : CollectionBase {...}
public class CustomEventArgs : EventArgs {...}
public class CustomException : Exception {...}
La scelta di un’opportuna convenzione sui nomi aiuta notevolmente il manutentore che deve comprendere il codice al fine di poterlo modificare.
Non esistono ancora convenzioni accettate universalmente.
È possibile, fissata una convenzione, realizzare strumenti di refactoring in grado di:
Ad esempio, JIndent
1. Introduzione
4. Casi d'uso
6. Class Diagram – parte prima
7. Class diagram – parte seconda
8. Class diagram – parte terza
9. Modellazione architetturale
10. Sequence Diagram
14. Progettazione Architetturale
15. Design Patterns – Parte prima
16. Design Patterns – Parte seconda
17. Progettazione dell'interfaccia utente
I. Sommerville, Ingegneria del Software, 8a edizione, capitolo 27.