OOP: Documentazione del Codice ad Oggetti

Alessandro Martinelli
alessandro.martinelli@unipv.it
25 Ottobre 2011
OOP: Documentazione del Codice ad Oggetti
UML:Diagrammi delle Classi
Linee Guida per il Codice
La Documentazione Javadoc
Fondamenti di Informatica II
UML: i Diagrammi delle Classi
UML: i Diagrammi delle Classi
A. Martinelli () Documentazione 25/10/2011 2 / 27
UML: i Diagrammi delle Classi
UML: Aspetti generali
UML sta per Unied Modeling Language e rappresenta un insieme di speciche
standard per la rappresentazione graca dei contenuti di un prodotto software.
Diagrammi delle Classi
I Diagrammi delle Classi sono uno dei tipi di Diagrammi UML. Con i Diagrammi
delle Classi si Mostra:
La struttura delle Classi
Le relazioni tra pi`u Classi
Come vedremo, esistono molti altri diagrammi UML per rappresentare aspetti
diversi di un progetto software.
A. Martinelli () Documentazione 25/10/2011 3 / 27
UML: i Diagrammi delle Classi
UML: Aspetti generali
In generale UML `e utile in due momenti:
Pianicazione
Durante la pianicazione lUML `e usato come strumento di valutazione;
Spesso i diagrammi sono incompleti, questo a riprova del fatto che no
allultima fase della pianicazione non si arriva a denire in modo completo la
struttura dei moduli di programmazione.
La pianicazione avviene nel primo stadio di un progetto, ma pu` o continuare in
qualsiasi fase del suo sviluppo.
Documentazione
Nella Documentazione lUML `e usato come strumento descrittivo;
I diagrammi sono pi`u completi, ma possono essere meno dettagliati.
La documentazione nasce durante lo sviluppo di un progetto, e deve essere
terminata alla ne dello sviluppo.
Col termine Draft (Bozza) si indicano le speciche di una API (Application
Programming Interface) ancora in fase di denizione.
A. Martinelli () Documentazione 25/10/2011 4 / 27
UML: i Diagrammi delle Classi
Diagrammi delle Classi: le Classi
Le Classi sono rappresentate come Rettangoli, allinterno del quale `e scritto il
nome della Classe.
Una coppia di rettangoli aggiuntivi pu` o accompagnare la classe per rappresentare
separatamente attributi e metodi.
A. Martinelli () Documentazione 25/10/2011 5 / 27
UML: i Diagrammi delle Classi
Diagrammi delle Classi: Metodi e Attributi
Il tipo di attributi, metodi e parametri dei metodi (che pu` o non essere specicato)
`e indicato con il simbolo : seguito dal nome del tipo.
Si indica la visibilit`a private e public con un carattere - (private) o + (public)
A. Martinelli () Documentazione 25/10/2011 6 / 27
UML: i Diagrammi delle Classi
Diagrammi delle Classi: Associazioni
Ogni volta che c`e una relazione tra due classi si utilizza la relazione di
Associazione, una linea continua che connette le due classi.
Notazione delle Associazioni
Agli estremi della linea di associazione si pu`o usare una freccia aperta.
La freccia indica una Dipendenza. Nellesempio, ad uno studente sono
associati dei corsi quindi, il modulo studente dipende dal modulo Corso
Ad ogni associazione, si pu`o assegnare una etichetta che fornisce un
signicato alla relazione. Nellesempio letichetta `e la parola partecipa.
Su ogni lato della associazione pu`o comparire il valore della Cardinalit`a.
Su ogni lato della relazione, `e possibile aggiungere una etichetta che
indica il ruolo del partecipante.
A. Martinelli () Documentazione 25/10/2011 7 / 27
UML: i Diagrammi delle Classi
Diagrammi delle Classi: Associazioni
Cardinalit`a delle Associazioni
[1]: La Classe partecipa sempre con 1 istanza alla relazione
[N]: La Classe partecipa sempre con N istanze
[0..1]: La Classe partecipa al pi`u con un elemento alla relazione
[0..] oppure []: La Classe pu` o partecipare con un numero indenito di
elementi alla relazione
[1..]: La Classe partecipa con almeno una istanza alla relazione
A. Martinelli () Documentazione 25/10/2011 8 / 27
UML: i Diagrammi delle Classi
Diagrammi delle Classi: Associazioni
Alcune associazioni possono essere arricchite col simbolo di Aggregazione, che sta
ad indicare che le istanze vengono realizzate aggregando istanze di una altra Classe:
Alcune associazioni possono essere arricchite col simbolo di Composizione, che
sta ad indicare che le istanze vengono realizzate componendo in numero variabile
le istanza di una altra Classe:
A. Martinelli () Documentazione 25/10/2011 9 / 27
UML: i Diagrammi delle Classi
Diagrammi delle Classi: Ereditariet`a
LEreditariet`a con una freccia in linea continua che va dalla Classe Figlia alla
Classe Padre. La freccia `e chiusa, e bianca allinterno.
A. Martinelli () Documentazione 25/10/2011 10 / 27
UML: i Diagrammi delle Classi
Diagrammi delle Classi: Astrazione
Nei diagrammi con Ereditariet`a, i moduli e i metodi astratti sono solitamente
indicati con un Font diverso, solitamente si utilizzano caratteri in Italic.
A. Martinelli () Documentazione 25/10/2011 11 / 27
UML: i Diagrammi delle Classi
Diagrammi delle Classi: Interfacce
Le Interfacce vengono segnalate con letichetta <<Interface>>.
LImplementazione di una interfaccia viene indicata con la stessa freccia
dellEreditariet`a, ma usando un tratto tratteggiato anzich`e continuo.
La freccia di estensione e quella di implementazione dieriscono solo per un
tratteggio. In fase di progettazione si usano indierentemente per indicare
generalizzazione: cos` si rimanda la decisione di utilizzare interfacce piuttosto
che classi astratte.
A. Martinelli () Documentazione 25/10/2011 12 / 27
UML: i Diagrammi delle Classi
Diagrammi delle Classi: Note
Essendo i Diagrammi delle Classi delle notazioni Grache, avete tutta la libert`a di
aggiungere Note a qualsiasi cosa. Solitamente le note sono inserite sotto forma di
riquadri con un angolo piegato, e una linea tratteggiata che connette la nota al
modulo (o metodo o attributo) che commenta.
A. Martinelli () Documentazione 25/10/2011 13 / 27
UML: i Diagrammi delle Classi
Diagrammi delle Classi: Package
I Diagrammi delle Classi consentono di rappresentare anche i Package, che sono
indicati come aree rettangolari contenenti classi, e aventi una etichetta nellangolo
che indica il nome del package.
NOTA
La seconda parte del 1

semestre del Corso di Fondamenti di Informatica II sar`a

loccasione per fare parecchi esempi di uso della notazione dei Diagrammi delle
Classi UML.
A. Martinelli () Documentazione 25/10/2011 14 / 27
Linee Guida Per il Codice
Linee Guida per il Codice
A. Martinelli () Documentazione 25/10/2011 15 / 27
Linee Guida Per il Codice
Un Esempio di Codice.
/ Questa c l a s s e s e r v e per or d i n a r e
un c e r t o numero di v a l o r i
s ot t o f orma di v e t t o r e /
pu b l i c c l a s s Oper at or e{
/Or di na un v e t t o r e di i nt , che v i e ne pas s at o
come par amet r o . /
p u bl i c s t a t i c voi d o r d i n a I l Ve t t o r e Di I n t e r i ( i n t [ ] v )
{ i n t i , c , n=v . l e ngt h ; // n `e i l numero di e l e me nt i ne l v e t t or e
i n t [ ] r=new i n t [ n ] ; / / Co s t r u i s c o un v e t t o r e di di mens i one n
f o r ( i =0; i <n ; i ++)//copi o v i n r
r [ i ]=v [ i ] ;
f o r ( i =0; i <n ; i ++){//Al gor i t mo di or di nament o
f o r ( j =i +1; j <n ; j ++){
i f ( r [ i ]>r [ j ] ) {
c=r [ i ] ; r [ i ]=r [ j ] ; r [ i ]=c ; // swap
}}}}
/Or di na un v e t t o r e di f l o a t , che v i e ne pas s at o come par amet r o . /
p u bl i c s t a t i c f l o a t [ ] r i o r d i n a I l Ve t t o r e Di F l o a t ( f l o a t [ ] v e t t o r e )
{ //TODO}
}
AAARGH!!!
A. Martinelli () Documentazione 25/10/2011 16 / 27
Linee Guida Per il Codice
Un Altro Esempio di Codice...
pu b l i c c l a s s Or di na t or e{
p u bl i c s t a t i c voi d or di na ( i n t [ ] daOr di nar e ){
i n t [ ] r e t ur nVa l =copi a ( daOr di nar e ) ;
f o r ( i n t i =0; i <daOr di nar e . l e ngt h ; i ++){
f o r ( i n t j =i +1; j <daOr di nar e . l e ngt h ; j ++){
i f ( r e t ur nVa l [ i ]>r e t ur nVa l [ j ] ) {
s cambi a ( r et ur nVal , i , j ) ;
}
}
}
r e t u r n r e t ur nVa l ;
}
p r i v a t e s t a t i c i n t copi a ( i n t [ ] v e t t or e ){
i n t [ ] r e t ur nVa l =new i n t [ v e t t or e . l e ngt h ] ;
f o r ( i n t i =0; i <v e t t o r e . l e ngt h ; i ++){
r e t ur nVa l [ i ]=v e t t or e [ i ] ;
}
r e t u r n r e t ur nVa l ;
}
p r i v a t e s t a t i c voi d s cambi a ( i n t v e t t or e , i n t i , i n t j ){
i n t tmp=v e t t o r e [ i ] ;
v e t t or e [ i ]=v e t t o r e [ j ] ;
v e t t or e [ j ]=tmp ;
}
p u bl i c s t a t i c f l o a t [ ] or di na ( f l o a t [ ] v e t t o r e ){
//TODO
}
}
A. Martinelli () Documentazione 25/10/2011 17 / 27
Linee Guida Per il Codice
Sulle Linee Guida
Il codice dei due esempi fa la stessa cosa, tuttavia il codice del secondo esempio `e
molto pi`u leggibile.
Un Buon Codice di Programmazione
Ci vuole meno tempo a leggere/scrivere dei nomi scelti correttamente che
interi commenti. I commenti sono superui se il codice `e chiaro e ben leggibile.
Un Buon Codice di Programmazione richiede luso di Linee Guida.
Le linee guida sono regole formali che non fanno parte del linguaggio di
programmazione e determinano come deve essere scritto il codice.
Le linee guida:
Aiutano a scrivere le cose sempre nello stesso modo.
Forniscono una prassi utile e condivisa che aiuta a capire il proprio codice
nonch`e quello scritto dagli altri.
A. Martinelli () Documentazione 25/10/2011 18 / 27
Linee Guida Per il Codice
Esempi di Linee Guida
Se scrivo un if, un for, un while etc. uso sempre le parentesi grae. La graa
in apertura `e posizionata in linea, quella di chiusura `e allineata alla i di if alla f
di for, alla w di while etc.
Uso il ciclo for unicamente se `e noto prima del ciclo il numero di volte che il
ciclo dovr`a ciclare (scorrimento di liste o vettori), senza mai usare un break; in
tutti gli altri casi, o se mi occorre il break, allora uso il ciclo while.
Le linee guida non sono parte della sintassi del linguaggio di programmazione, ma
dovrebbero diventare parte del vostro stile:
Non importa quali linee guida si adottino, ma `e importante che si adottino.
E utile ed importante che siano le stesse allinterno di un Team di Lavoro.
E inoltre utile allinearsi a quelle che sono riconosciute come linee guida
standard per un linguaggio di programmazione.
Nota sul Corso
In laboratorio saranno fornite le linee guida standard usate per il codice Java,
ovvero le linee guida usate dalla maggior parte della comunit`a di sviluppatori java a
livello internazionale.
A. Martinelli () Documentazione 25/10/2011 19 / 27
La Documentazione Javadoc
La documentazione uciale Java: i Javadoc
A. Martinelli () Documentazione 25/10/2011 20 / 27
La Documentazione Javadoc
I Javadoc
Il comando javadoc
Come java e javac, javadoc `e una delle funzionalit`a che si trovano nella cartella
bin del jdk (Java Development Kit).
javadoc esegue un parsing speciale dei le java, estraendo dei le di
documentazione in html, un le html per ogni le java.
I le html sono visualizzabili con un browser web.
javadoc genera inoltre menu e link al ne di rendere la documentazione
navigabile.
I le javadoc possono essere arricchiti con i commenti speciali javadoc:
Commenti Javadoc
/
Questo che i n i z i a con doppi o a s t e r i s c o `e un commento
Javadoc , e compar i r `a n e l l a document azi one di
ques t o f i l e .
/
A. Martinelli () Documentazione 25/10/2011 21 / 27
La Documentazione Javadoc
Il Javadoc di una Classe
/
Questo `e un commento Javadoc
che d e s c r i v e l a c l a s s e
JavadocTest
/
pu b l i c c l a s s JavadocTest {
p r i v a t e i n t v al ue ;
/
Questo `e un commento Javadoc
che d e s c r i v e i l metodo
t e s t
@param p par ametr o
@r et ur n i l v a l o r e di p
/
p u b l i c i n t t e s t ( i n t p){
r e t ur n p ;
}
}
A. Martinelli () Documentazione 25/10/2011 22 / 27
La Documentazione Javadoc
Il Javadoc di una Classe: Intestazione
Si notano:
Il package della Classe
Lalbero delle Ereditariet`a con la Classi Padre
Il Commento fornito sulla classe dal programmatore
A. Martinelli () Documentazione 25/10/2011 23 / 27
La Documentazione Javadoc
Il Javadoc di una Classe: elenco dei Membri pubblici
Si notino:
La Firma dei metodi
Il commento fornito dal programmatore sulla classe
A. Martinelli () Documentazione 25/10/2011 24 / 27
La Documentazione Javadoc
Il Javadoc di una Classe: dettagli dei Membri pubblici
Si notino:
I singoli commenti forniti
Il commento fornito alla variabile di ritorno.
A. Martinelli () Documentazione 25/10/2011 25 / 27
La Documentazione Javadoc
Il Javadoc di una Classe: le parole chiave
I javadoc possono essere arricchiti utilizzando allinterno dei commenti alcune
importanti parole chiave precedute dal simbolo @. Ad esempio:
@author seguito dal Nome dellautore, consente di visualizzare lautore della
Classe nel documento
@see seguito dal nome di alcune classi consente di creare un link a quelle classi
nel documento.
@param seguito dal nome di un parametro e da una descrizione consente di
descrivere quel parametro
@return seguito da un commento, consente di specicare che cosa viene
ritornato da un metodo.
A. Martinelli () Documentazione 25/10/2011 26 / 27
La Documentazione Javadoc
Javadoc e Linee Guida: Quando Commentare?
La regola doro `e semplice:
Si fornisce un commento completo in stile
Javadoc per ogni classe, attributo o metodo
dichiarati public.
Per tutti gli altri casi, vale una regola semplicissima:
Se senti il bisogno di commentare un qualsiasi
frammento di codice che non sia lintestazione
javadoc di un membro public, allora vuol dire che
il codice fa schifo.
A. Martinelli () Documentazione 25/10/2011 27 / 27