Porfirio Tramontana » 18.Ambienti di sviluppo e documentazione

Standard di documentazione

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.

Standard per la documentazione

• Standard per il processo di documentazione
  • Come i documenti vanno sviluppati, validati, manutenuti.
• Standard per i documenti
  • Descrivono la struttura, il contenuto e l’editing del documento.
• Standards per lo scambio/condivisione di documenti
  • Come i documenti vanno memorizzati e scambiati/condivisi tra differenti sistemi di documentazione.

Standard per i documenti

• Standard per l’identificazione di un documento
  • Come i documenti sono univocamente identificati;
• Standard per la struttura di un documento
  • Struttura standard per i documenti del progetto;
• Standard per la presentazione di un documento
  • Definizione di font, stili, uso di logo …
• Standard per l’aggiornamento di documenti
  • Definizione di come le modifiche di una precedente versione si riflettono in un documento.

Standard per lo scambio di documenti

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.

Documentazione del codice

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:

• Testing
• Integrazione
• Manutenzione
• Reverse Engineering e Reengineering

L’utilizzo di standard di documentazione noti presenta diversi vantaggi:

• Semplicità di scrittura della documentazione;
• Possibilità di valutare e verificare velocemente la completezza della documentazione;
• Possibilità di generare automaticamente manuali utente e diagrammi statici di dettaglio.

Qualità della documentazione del codice

La documentazione interna al codice dovrebbe essere:

• Coerente;
• Consistente
  • Non devono esserci ambiguità o contraddizioni;
• Conforme ad uno standard;
• Tracciabile
  • Deve essere possibile poter collegare, nella maniera più rapida possibile, i concetti presenti nel codice con la loro documentazione e con i concetti ad esso associati.

Standard di documentazione del codice

Tra gli innumerevoli standard di documentazione esistenti, verrà presentato Javadoc.

• Ideato per Java;
• Affiancato da un tool (javadoc) in grado di generare manualistica a partire dall’analisi della documentazione presente nel codice sorgente;
• Generalizzabile a qualsiasi altro linguaggio.

Come tool generante, oltre a javadoc, verranno mostrate le potenzialità di Doxygen.

Esempio Javadoc

HTML risultante

Principali Tag Javadoc

@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}

Principali Tag Javadoc (segue)

@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

Principali Tag Javadoc (segue)

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.

Doxygen

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/

Naming Guidelines

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).

Notazione ungherese

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.

Esempi di Notazione Ungherese

• f     flag booleano
  • fError
• ch    char
  • chChoose
• str    stringa
  • strText
• ptr    puntatore
  • ptrElement

Limiti della notazione ungherese

Non è strettamente necessaria in nessun linguaggio compilato.
Potrebbe essere utile al programmatore come elemento di tracciabilità della documentazione

• Ogni volta che viene utilizzata una variabile, il programmatore è consapevole del suo tipo
• Nei linguaggi a oggetti si evitano errori semantici dovuti ad errata interpretazione del tipo in casi di polimorfismo.

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.

Naming Convention Microsoft

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;

Naming Convention Microsoft (segue)

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();


Naming Convention Microsoft (segue)

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 {...}

Naming Convention

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:

• Valutare la conformità;
• Modificare il codice in modo da renderlo conforme.

Ad esempio, JIndent