La documentazione del software

Documentare bene gli oggetti e le funzioni create permette al programmatore di riutilizzarle più facilmente in futuro, quindi di fare un investimento per poter risparmiare tempo. Se la documentazione è in lingua inglese, chiunque conosce l'inglese potrà riutilizzare il software.

La documentazione del software può essere inserita nel software stesso, aggiungendovi degli opportuni commenti all'inizio di ogni file. Se il programma è costituito da più file sorgente, dovrebbe essere documentato anche ogni file, come in questo esempio.

/**
 * @file main.cpp
 * @author  Fabio <blabla@example.com>
 * @version 1.3
 *
 * @section LICENSE
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License as
 * published by the Free Software Foundation; either version 2 of
 * the License, or (at your option) any later version.
 * 
 */

A loro volta ogni classe e ogni funzione devono essere documentate come in questi esempi:

/**
 * @section DESCRIPTION
 *
 * The time class represents a moment of time.
 */
 
class Time {
 
    public:
 
       /**
        * Constructor that sets the time to a given value.
        *
        * @param timemillis Number of milliseconds
        *        passed since Jan 1, 1970.
        */
       Time (int timemillis); 
       static Time now ();
};

Esempio di documentazione di una funzione

/**
 * <una descrizione breve, di una riga>
 *
 * <una descrizione piu' completa>
 * <che puo' avere anche piu' righe>
 *
 * @param  descrizione dei parametri della funzione membro
 * @param  ...
 * @return descrizione dell'eventuale valore restituito
 */
void NomeClasse::nomeFunzione()
{
      // il codice della funzione...
}
  • appunti3s/documentazione.txt
  • Last modified: 2018/04/25 07:55
  • (external edit)