Tag Archives: tool

Documentare il proprio codice: una buona abitudine

Uno degli aspetti che personalmente tendo a curare nella scrittura del codice è la sua documentazione.

Non mi riferisco (solo) all’inserimento dei classici commenti utili per ricordare cosa fa una particolare riga di codice, ma alla stesura di quelle istruzioni per l’uso complete che vengono associate ai tipi di dati in generale, ai metodi e ai loro parametri, ai valori di ritorno, alle proprietà, ai campi e così via.

Ritengo si tratti di un’attività fondamentale, soprattutto quando si lavora in team, affinché diversi sviluppatori possano conoscere immediatamente quali sono le funzionalità di una determinata classe, o qual è lo scopo di un metodo e dei parametri da specificare, senza dover perdere tempo ad analizzare il codice implementativo, ammesso che questo sia disponibile e che sia scritto in modo chiaro o almeno commentato. La disponibilità immediata di informazioni riguardo una generica API riduce drasticamente i tempi di sviluppo e proporzionalmente aumenta la produttività di chi ne fa uso, recuperando il tempo impiegato nella stesura della documentazione.

Qualsiasi tool di sviluppo moderno consente di scrivere queste informazioni direttamente nel codice, utilizzando specifiche convenzioni e marcatori (tag), e all’occorrenza di estrarle automaticamente (in formato XML nella maggior parte dei casi) per essere “processate” da un tool esterno per generare una guida in linea consultabile da coloro che utilizzeranno quel codice, magari compilato e referenziato come assembly o package.

Parlando nello specifico di Delphi e Visual Studio, entrambi gli ambienti forniscono allo sviluppatore – rispettivamente attraverso le tecnologie Code Insight e IntelliSense – facilitazioni per l’inserimento della documentazione nel codice: attraverso Code Insight, Delphi fornisce specifici “template” che generano in automatico il commento che contiene lo “scheletro” in cui inserire il testo, e Visual Studio addirittura suggerisce i tag che è possibile utilizzare per suddividere le varie parti della guida (ad esempio, il sommario, le annotazioni, i riferimenti ad altri tipi di dati, ecc.).

Qui sotto riporto un esempio di documentazione XML riferita alla classe che costituisce la finestra principale di un’applicazione VCL tipica di Delphi:

type
  ///	<summary>
  ///	  Rappresenta la finestra principale dell'applicazione.
  ///	</summary>
  ///	<remarks>
  ///	  Questa finestra contiene tutti gli elementi che consentono di accedere
  ///	  alle funzionalità dell'applicazione. Quando viene chiusa,
  ///	  l'applicazione termina.
  ///	</remarks>
  TMainForm = class(TForm)
  public
    ///	<summary>
    ///	  Provvede a impostare lo stato iniziale dei controlli della finestra.
    ///	</summary>
    ///	<remarks>
    ///	  Questo metodo deve essere invocato al momento della creazione della
    ///	  finestra, o quando è necessario ripristinare lo stato iniziale dei
    ///	  controlli.
    ///	</remarks>
    procedure InitializeControls;
  end;

Questa invece è la documentazione scritta per una classe C# analoga in Visual Studio:

    /// <summary>
    /// Rappresenta la finestra principale dell'applicazione.
    /// </summary>
    public partial class MainForm : Form
    {
        /// <summary>
        /// Inizializza una nuova istanza della classe <see cref="MainForm"/>.
        /// </summary>
        public MainForm()
        {
            // Invoca il metodo che inizializza i componenti
            InitializeComponent();
        }
    }

Sia Delphi che Visual Studio condividono la stessa tecnologia di documentazione, pertanto le convenzioni e i marcatori (tag) sono gli stessi in entrambi. Per un approfondimento a riguardo, potete consultare il sito MSDN.

Nonostante l’aiuto e il discreto supporto fornito da questi ambienti di sviluppo, molto spesso l’attività di documentazione del codice viene considerata comunque un’attività tediosa, in pratica tempo sprecato e sottratto allo sviluppo. La soluzione non è rinunciare a documentare il codice, ma cercare di accelerare questa attività sfruttando diversi tool esistenti e addirittura gratuiti (nelle loro versioni di base, comunque efficaci anche se limitate).

Documentation Insight in Delphi XE2In Delphi XE2 è stata integrata la versione “Express” di Documentation Insight, un tool davvero utile ed efficace prodotto da DevJET Software che semplifica la stesura della documentazione in Delphi: basta posizionarsi sull’elemento che si vuole documentare (classe o tipo, dichiarazione di un metodo o di una proprietà e così via) e premere la combinazione di tasti CTRL+SHIFT+D per richiamare la finestra che consente di inserire il testo e visualizzarne un’anteprima. Si tratta di un tool estremamente comodo e pratico, che inserisce nel modo corretto il commento nel codice risolvendo problemi non banali come il ritorno a capo automatico senza eccedere la lunghezza standard della riga.

GhostDocPer Visual Studio (2008 e 2010) suggerisco invece un paio di valide alternative: GhostDoc, acquisito da SubMain, semplice e immediato da utilizzare e disponibile anche in versione “Pro” con funzionalità aggiuntive, e Atomineer Utils, gratuito e più articolato e complesso del precedente, ma anche più impegnativo da configurare a dovere.

Entrambi i tool associano la classica “hot key” CTRL+SHIFT+D alla generazione automatica del commento di documentazione, e provvedono in alcuni casi a inserire modelli di contenuti già pronti, includendo ad esempio frasi fatte di uso frequente, addirittura anche in lingua italiana.

I siti di approfondimento dei tool contengono inoltre risorse che descrivono l’importanza e i benefici derivanti dal documentare a dovere – oltreché commentare – il proprio codice sorgente.

Si tratta di una buona abitudine che suggerisco a qualsiasi sviluppatore di acquisire.

Copyright © 2017. Powered by WordPress & Romangie Theme.