Newsgroup: it.comp.programmare
Titolo: Il problema della documentazione secondo voi

Prendo spunto dal post sui socket, in cui l'autore si lamentava di 
quanto fosse complessa la ricerca e la documentazione sulle librerie e 
sui protocolli esistenti: in effetti anche a me, quando vado a leggermi 
la documentazione di qualche libreria software (ultima in ordine di 
tempo la WinLib) mi sembra di perdere un sacco di tempo a sorbirmi 
chiacchiere, mentre gradirei molto di pi� sapere in modo veloce cosa 
fanno, in linea di massima, gli oggetti componenti e perch� sono stati 
creati cos� e non in un altro modo, e poi una descrizione pi� 
approfondita delle classi e dei loro metodi.
Invece molto spesso leggo pagine e pagine di discorsi sui massimi 
sistemi, le propriet� mirabili del framework e/o della libreria, della 
OOP con cui � stata scritta e degli oggetti software implementati, e poi 
una descrizioncina stringata e insufficiente delle classi e dei metodi 
(o delle funzioni), e questo � tutto. :-(
Mancano molto spesso dei casi particolari, o spesso vengono date per 
scontate delle condizioni iniziali che non lo sono sempre, o magari ci 
sono effetti collaterali che non vengono descritti. A volte sono dei 
bug, ma molto pi� spesso � proprio che certe cose avrebbero dovuto 
essere scritte a chiare lettere nella doc e invece non c'erano. Cos� uno 
si becca la sorpresa e deve smadonnare per cavarsela :-((
Volevo sapere se questa, che � una mia sensazione da alcuni anni, � un 
sentimento comune anche ad altri oppure no... ma secondo voi davvero la 
doc di librerie, framework, protocolli, standard, interfacce, API � di 
solito frammentaria, incompleta e in genere scritta male?

 male?
Per me ovviamente sì; di fatto per molte cose
dipendo dall'aiuto altrui. Il problema non è tanto
la documentazione (o meglio, è spesso un grosso
problema pure quello) quanto la enorme
frammentazione delle soluzioni. Addirittura, come
dicevo, non trovo le cose perché non so che parole
chiave cercare e ormai google ostacola più che
aiutare, a causa di tutti quei siti che generano
dinamicamente risposte che non c'entrano niente.
Ammesso di trovare tutto, io ho qui sul PC una
dozzina abbondante di librerie matematiche e un
altro paio di dozzine di varia specie. Una compila
con borland e non con MinGW, l'altra con VisualC e
MinGw ma non con borland, altre con nessuno dei tre.
Il porting spesso è pazzesco e si sa che non
conviene mai tentare. Ho girato tutti i compilatori
sperando di trovarne uno che fosse usato non dico da
tutte ma dalla maggior parte delle librerie. Inutile
dire che non esiste.
Già esistesse un protocollo accettato da tutti sugli
standard minimi comuni dei progetti sarebbe un bel
passo avanti.
Di fatto molte cose faccio prima a riscrivermele ma
solo quando so che sono compiti limitati e
relativamente gestibili. E spesso - qui mi
riallaccio a te - non posso usare librerie perché la
documentazione o non ha un tutorial o ne ha uno
cretino e poi passa ai massimi sistemi. Sicuramente
per mia colpa di non aver trovato un tutorial
progressivo ma un ottimo esempio di questa
documentazione senza passaggi intermedi mi pare sia
proprio boost. Del 99% di boost io non riesco a
capire nemmeno cosa faccia.
Ciao! E grazie sempre del vostro aiuto che apprezzo
molto.
Apx.
-- 
Perché gli iraniani odiano il vento?
Perché gli sbatte tutte le persiane.