Newsgroup: it.comp.lang.c
Titolo: doxygen sì doxygen no

Sono convinto che commentare l'ovvio sia peggio che non commentare
qualcosa di ben scritto.
Ho comunque provato ad installare doxygen e sto generando la
documentazione, a questo punto però in un certo senso mi scoccia non
commentare delle funzioni, perché la doc generata rimane in qualche modo
incompleta.
Ma a vedere codice altrui in cui per 6 righe di codice ci sono 4 righe
di commento inutile (si capisce benissimo comunque cosa prende in input
e cosa ritorna) mi viene la nausea.
Voi come vi comportate?


Personalmente ritengo che bisogna commentare solo:
- il modulo in testa al file .h (cosa fa questo modulo? come? il flow
tipico? etc.etc.). Mi raccomando il .h perché non è detto che il .c
sarà sempre disponibile nell'ambiente finale.
- sopra le funzioni nel file .c solo se la funzione fa qualcosa di
strano, implementa un'algoritmo particolare, o comunque contiene
qualsiasi cosa che ritieni sia non immediato da leggere a prima vista.
Ovvero, una funzione di due righe non la commenti, ma un bel magheggio
di puntatori tipico del c ovviamente sì (magari anche scrivendo perché
ti sei andato a complicare la vita).
- quando c'è una parte di una funzione che è incompleta (tipo un
ritorno non controllato perché vai fretta, o un caso particolare non
gestito perché poco plausibile) *sempre* aggiungere un commento TODO o
FIXME, che vengono sia riconosciuti dalla maggior parte degli editor
che facilmente ritrovabili con un grep. Io utilizzo questa tecnica
anche per tenere traccia di ciò che manca, invece che utilizzare un
file di testo esterno, o ancora peggio una mail o un pezzo di carta.
Tutto il resto secondo me è fuffa.
Doxygen è stato creato (e si utilizza pure) NON per essere comodo per
il programmatore, ma per eliminargli il peso di dover scrivere una
documentazione decente, cosa che, si sa, non piace a nessuno.
Personalmente piuttosto che fare la figura dello svogliato preferisco
chiedere due/tre ore per scrivere un documento sulla mia roba, invece
di fare una figura patetica e prendermi i colpi da chi la mia roba la
utilizzerà (le ore non mi vengono mai concesse, ma tanto meglio: senza
documentazione l'utilizzatore finale si va a leggere i commenti di cui
sopra sul codice che sono molto più esplicativi e contestuali di
qualsiasi .txt/.pdf/.odt che sia).
Tutto questo sempre secondo me e soprattutto secondo l'esperienza che
mi sono fatto nei posti dove ho lavorato: sicuramente in ambienti
diversi le necessità saranno altre. Ovviamente nelle aziende grosse
grosse ci sono delle regole precise da seguire e in molte non puoi
neppure sgarrare (dove sono io adesso ad esempio ci sono regole
diverse per il codice del prodotto finale e per quello di componenti
condivisi), e dall'altro lato se lavori da solo puoi fare come ti
trovi meglio te.
Ciao!
P.S. Mi raccomando commenta sempre sempre sempre in inglese. Pensa
agli altri: siamo nel 2010, c'è internet e non c'è niente di peggio
che trovare il codice che ti serve commentato in polacco.

 che trovare il codice che ti serve commentato in polacco.
Sì sì chiaro, in generale mi viene l'orticaria a scrivere di informatica
in italiano, tanto devo comunque spararci dentro il 50% dei termini in
inglese quindi viene fuori una schifezza...
Io ultimamente ho visto codice NON COMMENTATO e scritto con il deretano
ma con la sua bella documentazione auto-generata e totalmente inutile.
Oppure codice scritto molto bene ma con la metà delle linee a
documentare l'ovvio, mi sembra che entrambe le vie siano da evitare.
Ora devo vedere un come si configura questo doxygen, ma in sostanza mi
basterebbe che mi facesse vedere tutte le funzioni e mi sembra di capire
che possa generare dei grafi delle chiamate tra di esse.
Questo basta ed avanza, anche se mi scoccia un po' che alcune siano
documentate ed altre no, sembra una mancanza mentre è solo (secondo me)
risparmio di fatica inutile.