La documentazione del software, Salvatore Cuomo « Programmazione II - Laboratorio « Scienze Matematiche Fisiche e Naturali

Allocazione dinamica: Esempio 1

Problema

Si vuole calcolare il prodotto di due vettori utilizzando un elemento di software scritto da altri.

Si vuole utilizzare il codice sorgente di un programma come se fosse una scatola nera (black-box) ovvero vogliamo fornire un dato di input ed ottenere “senza problemi” l’output.

Prodotto tra vettori.

Scatola nera.

Codice sorgente 1/2

Codice non commentato 1.

Codice sorgente 2/2

Codice non commentato 2.

Considerazioni

L’utilizzatore del codice sorgente si trova diversi punti da risolvere:

Non conosce l’elemento di software quale problema risolve
Non conosce le specifiche per richiamare in un proprio programma l’elemento
Non conosce quale output viene restituito.

L’elemento di software in questione non e’ usabile

Scatola nera 2.

Qualche commento -Codice sorgente 1/2

Codice commentato 1.

Qualche commento -Codice sorgente 2/2

Codice commentato 2.

Documentazione interna

L’inserimento nel codice sorgente di qualche commento ha consentito di rendere l’elemento di software maggiormente comprensibile.

La documentazione interna risulta dunque essere la prima interfaccia tra l’ utente e l’elemento di software che si intende adoperare.

Il “buon senso” ci suggerisce che:

” una buona documentazione interna è indice di un elemento di software scritto bene”

Volendo stabilire una convenzione su cosa debba essere presente nella documentazione interna essa deve riportare:

Una descrizione dello scopo e delle variabili di input e di output
linee di commento essenziali nei punti nevralgici del programma

Documentazione esterna

L’elemento di software è il risultato di un complesso percorso di progettazione i cui principali punti sono:

La formalizzazione del problema da risolvere
La descrizione mediante un algoritmo
L’implementazione dell’algoritmo in un linguaggio di programmazione

Il processo descritto nei punti precedenti è un processo osmotico, ovvero da una fase si passa ad una altra potendo anche tornare indietro.

Al fine di utilizzare al meglio la “scatola nera” (black – box) è necessario fornire un buon “manuale d’uso”

Bisogna in ogni caso fornire una “documentazione esterna” di utilizzo!

Scatole nera 3.

Documentazione.

Documentazione esterna

Documentazione Est 1.

Documentazione esterna

Documentazione Est 2.

Libreria NAG

Quella riportata nell’esempio è:

f06eaf.f

una routine della libreria matematica NAG del capitolo f06 dedicato alle operazioni di base di algebra lineare.

E’ la versione Nag della routine:

DDOT()

di un’altra libreria per l’algebra lineare numerica Blas (livello I).

NAG

Documentazione esterna

Come utile base di lavoro per la documentazione esterna di elementi di software in un corso di base di programmazione stabiliamo alcune convenzioni rispetto alla documentazione esterna. Di seguito si riportano i punti che generalmente dovrebbero essere presenti in un buon manuale d’uso.

1. Scopo. 2-3 linee che descrivono quale tipo di problema l’elemento di software risolve. Ad esempio:

Scopo. La procedura void matvet() calcola il prodotto A*x= y di una matrice di dimensione n x m per un vettore.

2. Specifiche. Il prototipo della funzione che indica quali siano i parametri di Input/Output della funzione. Ad esempio: void matvet (float **A, int n, int m, float *x, float *y)

3. Descrizione. Breve descrizione dell’algoritmo principale su cui si base l’elemento di software. Tale punto quando necessario deve riportare anche le possibili strategie implementative.

Documentazione esterna

4. Riferimenti bibliografici. Le principali fonti da cui si sono tratte specifiche implementative o algoritmi di base.

3. Lista dei parametri. Un elenco dei paramatri di input/output della funzione con relativa specifica del tipo. Ad esempio

In input:

A. Reale. Matrice che si vuole moltiplicare.

n. Intero. Numero di righe della matrice A.

m. Intero. Numero di colonne delle matrice A.

x. Reale. Vettore che si vuole moltiplicare

In output:

y. Reale. Risultato del prodotto A * x.

5. Funzioni ausiliarie. La descrizione e le specifiche di eventuali funzioni ausiliarie richiamate dalla funzione che si stà descrivendo.

Documentazione esterna

6. Complessità di tempo e di spazio. La descrizione del numero asintotico di operazioni che l’algoritmo principale implementato nella funzione espleta. Bisogna inoltre anche riportare la memoria che l’elemento di software alloca.

7. Accuratezza fornita. Il tipo di errore presente sul risultato della procedura e l’accuratezza con cui esso è fornito.

8. Indicatori di errore. Eventuali variabili utilizzate come indicatore di errore. Il valore di eccezione che esse registrano con una indicazione del tipo di errore registrato.

9. Esempio d’uso. Si deve riportare il listato di un “tipico” programma principale che richiami la nostra funzione con i risultati che esso produce una volta che è stato mandato in esecuzione.