[Python] Agile programming Robert Martin

[Nicola Larosa]

> Simone Federici wrote:
>> Ok vediamo un modulo più semplice 100 linee. Tu lo ritieni
>> sbagliato scrivere il commento nell'eccezione in fondo al modulo?
>> https://raw.githubusercontent.com/django/django/master/django/utils/tzinfo.py

Marco Beri wrote:
> Eh, eh... chiaramente no, non solo non è sbagliato secondo me, ma è
> pure utile.

Più che utile, lo ritengo indispensabile.


> Come sempre non esiste regola senza eccezioni

Nel libro Clean Code l'autore non ha proposto una regola, ma una sua
convinzione. Il suo giudizio sui commenti è complessivamente negativo, ma
piuttosto articolato e con parti positive, vedi l'incipit del cap. 4 a p.
53: "Nothing can be quite so helpful as a well-placed comment." e la
sezione "Good Comments" a p.55.


> Non direi certo che il commento del tuo esempio è una sconfitta del
> programmatore, ma venendo da un'epoca in cui il codice DOVEVA essere
> commentato,

Un'epoca? Il codice deve essere commentato e descritto anche oggi.


> la definizione seguente mi ha abbastanza colpito: "ogni commento non
> banale è un insuccesso del programmatore che non è riuscito a scrivere
> del codice auto-esplicativo".

Credo sia questa:

"Comments are, at best, a necessary evil. If our programming languages
were expressive enough, or if we had the talent to subtly wield those
languages to express our intent, we would not need comments very
much—perhaps not at all."

L'autore descrive in modo articolato pregi e difetti dei commenti; il suo
giudizio complessivo che sia un "male necessario" mi sembra miope.

	
Ci sono vari livelli di testo umano, non comprensibile dalle macchine
(almeno non oggi, e speriamo mai), collegato ai programmi per computer.
Si va dalle specifiche, alle descrizioni architetturali, alle specifiche
delle API, alle docstring, ai commenti veri e propri.

*Tutti* questi livelli sono *essenziali*. Per l'accennata insufficiente
espressività dei linguaggi di programmazione, scrivere programmi è
un'attività a perdita di conoscenza: il dettaglio delle operazioni
comprensibili dalla macchina non conserva l'intenzione del programmatore.

Ogni volta che si legge un programma privo di documentazione si effettua
un'operazione costosa di "reverse intentioning", non dissimile dal
"reverse engineering" ma ad un livello superiore.

Scrivere codice corretto è difficile, scrivere codice espressivo lo è
ancora di più, scrivere contemporaneamente codice espressivo e il testo
che completi quell'espressività, inevitabilmente insufficiente, è
difficilissimo e non gode della verifica automatica, da cui la tipica
insofferenza dei programmatori, pigri per definizione.

La necessaria manutenzione del codice comporta la manutenzione della sua
descrizione testuale: ma senza quella descrizione, la stessa manutenzione
è molto più costosa e pericolosa.

Siamo chiamati ad essere contemporaneamente meccanici, domatori,
scrittori e poeti: non meraviglia che tendiamo ad alleggerire il
fardello. Ahimè, non è una buona idea.

-- 
Nicola 'tekNico' Larosa <http://www.tekNico.net/>

The insight that _doing too much, too fast causes serious problems_,
is a core life truth that is gaining recognition in more and more fields
from neurology to psychotherapy to bodybuilding to personal relationships
to product design to engineering to project management to social systems
to basic science and philosophy to art to sex. - Johann Gevers, May 2014