Vai alla Home Page About me Courseware Federica Living Library Federica Federica Podstudio Virtual Campus 3D Le Miniguide all'orientamento Gli eBook di Federica La Corte in Rete
 
I corsi di Scienze Matematiche Fisiche e Naturali
 
Il Corso Le lezioni del Corso La Cattedra
 
Materiali di approfondimento Risorse Web Il Podcast di questa lezione

Salvatore Cuomo » 11.La documentazione del software


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.

Prodotto tra vettori.

Scatola nera.

Scatola nera.


Codice sorgente 1/2

Codice non commentato 1.

Codice non commentato 1.


Codice sorgente 2/2

Codice non commentato 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.

Scatola nera 2.


Qualche commento -Codice sorgente 1/2

Codice commentato 1.

Codice commentato 1.


Qualche commento -Codice sorgente 2/2

Codice commentato 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:

  1. La formalizzazione del problema da risolvere
  2. La descrizione mediante un algoritmo
  3. 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.

Scatole nera 3.

Documentazione.

Documentazione.


Documentazione esterna

Documentazione Est 1.

Documentazione Est 1.


Documentazione esterna

Documentazione Est 2.

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

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.

  • Contenuti protetti da Creative Commons
  • Feed RSS
  • Condividi su FriendFeed
  • Condividi su Facebook
  • Segnala su Twitter
  • Condividi su LinkedIn
Progetto "Campus Virtuale" dell'Università degli Studi di Napoli Federico II, realizzato con il cofinanziamento dell'Unione europea. Asse V - Società dell'informazione - Obiettivo Operativo 5.1 e-Government ed e-Inclusion