ASCII Art per il "source code commenting"

Cosa c'entra questo post con la Sicurezza? Nulla o quasi, ma non posso essere monotematico, no?

A chi non è capitato di scrivere del codice sorgente. L'essenza dell'Informatica in fondo è questa: algoritmi, ottimizzazioni, stile di programmazione, commenti...COMMENTI!

Commentare il codice, a meno che non siate discepoli dell'oscura arte del "Security Through Obscurity" o della "Obfuscation", è fondamentale per la manutenzione e l'evoluzione di applicazioni software. E al giorno d'oggi commentare il codice non è nemmeno tanto costoso perché quasi tutti i linguaggi, o meglio gli ambienti di programmazione, mettono a disposizione scorciatoie che, in modo quasi automatico, inseriscono la struttura del commento nella signature dei metodi per esempio. Basta poi aggiungere la dovuta descrizione ed il gioco è fatto.

Certamente non bastano i commenti alle sole Classi, Metodi, Funzioni, etc. Anche gli algoritmi e le singole righe di codice spesso debbono essere commentate. Ma provate a commentare quell'algoritmo su cui avete sbattuto tanto la testa, con le sole parole: non basterebbe una pagina, e poi chi la leggerebbe?

Un semplice schema grafico però risolverebbe il tutto. 

Ma di solito gli schemi sono fuori dal codice sorgente (e magari nemmeno referenziati), in polverosi manuali o in file di Help dispersi negli hard disk. Insomma RTFM, direbbe qualcuno! E allora siamo costretti a spiegare in modo prolisso quale sia il particolare approccio, o il particolare algoritmo, senza poter inserire uno straccio di schema. Se va bene, perché in alcuni casi ci si rinuncia direttamente con l'esclamazione "tanto c'è il codice che documenta"!

Ma allora perché non sfruttare la cosiddetta "ASCII Art" per inserire degli schemi direttamente nei commenti? Si crea lo schema con un qualsiasi programma di disegno e poi lo si converte con i numerosi programmi on-line (quale per esempio www.Text-Image.com).

Non pensiate però che la conversione in ASCII possa essere utilizzata così com'è. Inevitabilmente le scritte dovranno essere riadattate a mano, ma avrete comunque raggiunto comunque il vostro scopo. Finalmente guardando quel complesso algoritmo potrete coglierne subito l'essenza grazie a quello schema un po' old-style!

Che poi, a guardar bene, il "code commenting" ha comunque a che fare con la sicurezza. Codice poco o per nulla commentato si predispone a bug che sappiamo bene possono lasciar aperta la porta a codice malevolo. 

In ultimo vi segnalo questo "epocale" articolo del compianto Jef Raskin, dal titolo "Comments are More Important than Code".