Newsgroup: it.lavoro.informatica
Titolo: commenti nel codice

ma da voi i commenti nel codice si usano?
perch� qui vige da sempre la prassi di non scrivere nessun commento, nemmeno 
due righe sommarie su cosa fa una funzione... Io ogni tanto ce li metto, ma 
mi sembra di essere l'unico.. 

Joe wrote:

frustali 
senno se per caso ci devi mettere le mani te 
son dolori 

 son dolori
ah lo so, altro che per caso, succede tutti i giorni. ormai ci sono abituato 
a perdere ore nel cercare di capire cosa fa un pezzo di codice scritto alla 
cazzo e senza commenti. Per questo mi chiedo se sia la consuetudine o solo 
la prerogativa della societ� triste per cui lavoro 

 ma da voi i commenti nel codice si usano?
Io ho lavorato in ambienti dove si scrive tonnellate di codice, ed in
ambienti dove non si scrive una riga di codice (ma il codice deve
essere leggibile ed autodocumentante), ed in n casi intermedi. Alla
fine mi riesco ad adattare abbastanza bene ai vari approcci, ed oramai
da anni nel mio book ho esempi di codice con commento e senza
commmento (autodocumentanti), ed in sede di intervista specifico
sempre la mia neutralità sull'argomento per quanto riguarda il lavoro
in collaborazione.
A livello personale, se dipendesse da me, un po di commento, non lo
vedrei male, anche in presenza di codice autodocumentante.
--
ale
http://ale.riolo.co.uk

 ce li metto, ma mi sembra di essere l'unico..
Qui dove?
Perche, a meno che non parliamo di un progetto di un migliaio di righe
o meno, il commento e cosa buona e giusta.
-- 
Ciao!
Luca

Joe wrote:

mah 
dipende da come organizzano il lavoro ... 
se c'e' un capo progetto che controlla o meno ... 
diciamo che per me, dipende da team a team... In funzione anche se il lavoro
e' interno o da affidare con tutti i sorgenti al cliente finale ... 
Quindi in una stessa societa' puoi trovare progetti con un commento ogni
nmila linee di codice e progetti con tutto fatto a regola d'arte
ciao 

 mi sembra di essere l'unico.. 
Da me sì. A parte che le funzione publiche sono (ovviamente)
rigorosamente gtkdoc'izzate oppure doxygen'ate, quasi tutti quelli che
conoscono documentano porzioni di codice non trivialissime.
-- 
Salvatore Iovene
http://www.iovene.com/
http://www.geekherocomic.com/

 ma da voi i commenti nel codice si usano?
C'è sempre la malaugurata prassi di alcuni colleghi di commentare le cose ovvie 
e tralasciare quelle ostiche... Sono anni che lo vedo. :-( 
Comuque i commenti peggiori sono quelli "pretesi" dal C#:
/// <summary>Get selected page list</summary>
List<Page> GetSelectedPages()
{
...
}
Ma cribbio, uno scrive una funzione chiara e lampante e devo pure commentarla? 
Ed anche in formato simil-xml???
Mah... Io mi rifiuto, ho altro da fare.
-- 
__________________________________
Luc (36, CO)
25 years uninterrupted programming
__________________________________


Io commento sempre e in maniera approfondita. Sopratutto lo faccio per 
me, visto che poi al 99% sono io che devo rimettere le mani sul mio 
vecchio codice.
I miei colleghi commentano molto poco, ma l'importante (per me) � che 
commentino le interfacce di accesso ai loro moduli.
-- 
Soprano

 vedrei male, anche in presenza di codice autodocumentante.
Sono d'accordo, è una cosa variabile. Per chi conosce a memoria un
certo software un certo commento può essere  sufficiente per lui ma
insufficiente per un estraneo.
Od anche sufficiente per lui in un dato momento, ma insufficiente per
lui stesso dopo solo 2-3 mesi di lontananza!
A livello aziendale, il commento veramente dettagliato può essere un
costo di una certa rilevanza. Se non altro perchè senza un controllo
centralizzato è molto difficile che i commenti abbiano una sufficiente
qualità ed uniformità.

 Mah... Io mi rifiuto, ho altro da fare.
Sono d'accordo con te. Un conto se la logica del codice ï¿œ complicata (a 
parte che se fosse troppo complicata ci sarebbe qualcosa che non va 
nell'implementazione, ma questo ï¿œ un altro discorso).
Ma quando il codice ï¿œ ovvio, inutile riempire di commenti.
C'ï¿œ chi sostiene che i commenti devono essere chiari, ma il codice ï¿œ 
meno importante che lo sia. Io credo invece che debba essere chiaro 
innanzitutto il codice, perchï¿œ alla fine ï¿œ quello che va fatto "girare", 
non i commenti.

 non i commenti
Dipende se esiste una documentazione esterna al programma, tipo
pseudocodifica, o no.
Nel secondo caso un codice poco o niente commentato è illeggibile da
chi non è esperto di quel linguaggio.
Pensa se devi fare un porting, es. da Cobol a Java (caso concreto).
Io direi che buona regola è commentare almeno per quello che
servirebbe per ripartire rapidamente, se lo stesso autore dovesse
riprendere in mano il programma dopo 6-12 mesi. Quello è probabilmente
il minimo accettabile.

 Mah... Io mi rifiuto, ho altro da fare.
In linea di massima sono d'accordo, ma il "simil-xml" ti permette di
generare in automatico la documentazione dei metodi e delle propriet�.
PaF

 se c'e' un capo progetto che controlla o meno ...
.. e se ci sono programmatori cazzoni e imbecilli ,  no?
Sempre con sta mentalita' da bambini di cinque anni che se non c'e' la
mamma che sorveglia...

 ma da voi i commenti nel codice si usano?
Certamente. Sul codice nuovo in genere metto anche quelli da  estrarre
in automatico per generare documentazione e quando si ha tempo (mai :-
( ) aggiorno vecchio codice poco commentato.
La chiarezza e' fondamentale per cui il commento e' insostituibile.
C'ya
   STeve

 
un mio collega:
"int flat_sum(int,int,&int);"
commento:
"// esegue una serie di operazioni su due numeri"
a cui il mio responsabile chiese:
- ma scusa non puoi scrivere qualcosa di piï¿œ nei commenti?
e lui
"// esegue una serie di operazioni su due numeri"
"// se la chiami."
detto tutto.
Personalmente tempo fa ero stato incaricato di buttare giï¿œ un minimo
comune denominatore dello scrivere e commentare codice e avevo deciso di
seguire l'Allman style (con alcune modifiche) per il codice, e lo stile
javadoc per i commenti. (anche quando uso altri linguaggi)
il che si traduce in:
(per il codice)
* indentatura di 4 spazi (fatta con gli spazi non con tab)
* le graffe stanno su una riga per conto loro
* per gli if si mettono sempre e comunque le graffe
ex:
if (10 == accessi)
{
   mostra_questionario = true;
}
* classi CamelCase, metodi lower_case, costanti e enum: UPPER_CASE
* i confronti con costanti prevedono l'uso della costante a sinistra, ex:
if(5 == accessi)
che aiuta i nuovi arrivati a non scrivere assegnamenti tipo if(a=5)
per i commenti:
/**
 * descrizione estesa del metodo e dei paramatri
 * bla, bla, bla, bla
 * bla, bla, bla, bla
 * ritorna il meta tag desiderato dell'url
 *
 * @param  url      un url assoluto nella forma 
http://www.miosito.com/
 * @param  meta_tag nome del tag meta di cui voglio sapere il valore
 * @return          una stringa contenente il valore del tag cercato
 * @see             URL,string
 */
public string getMeta(URL url, String meta_tag);
avevo persino proposto per chi non seguiva questo schema: denudazione
pubblica, gogna, fustigazione, amputamento delle mani ma dopo una
settimana tutti tornarono a scrivere il codice a cazzo senza commenti,
mescolando i case, eccetera, eccetera...
Io ho tenuto questo stile e il mio codice modestamente ï¿œ uno tra i piï¿œ
leggibili dove lavoro.
altri miei colleghi hanno invece la fissa dell'indispensabilitï¿œ
(specialmente i consulenti esterni) che si traduce nel:
* scrivere codice a cazzo che solo io posso toccare
* non mettere i commenti
* io divento indispensabile perchï¿œ sono l'unico che ci puï¿œ fare
manutenzione.
mah ad ognuno il suo...

 commentino le interfacce di accesso ai loro moduli.
quoto.
ma lavoriamo assieme?
ah già, tu sei nel quarto reich.
--
FabMind

 mi sembra di essere l'unico..
Quando programmavo io ce li mettevo.
Pero' da quando hanno inventato il "pagamento ad ore" ho smesso
di metterceli (dietro richiesta di velocizzazione).
Ciao,
Marco
-- 
questo articolo e` stato inviato via web dal servizio gratuito 
http://www.newsland.it/news
 segnala gli abusi ad 
ab...@newsland.it

 "// se la chiami."
a quel punto gli avrei risposto:
chiama questa:
MyWork.setEndDate (today)
-- 
Soprano

 di metterceli (dietro richiesta di velocizzazione).
Bisogna proprio non vederci al di là del proprio naso per non capire
che:
1) commentare il proprio codice aiuta anche a capirlo meglio, e quindi a
scrivere codice migliore
2) commentare il codice renderà più produttivo chi rimette le mani sullo
stesso codice dopo qualche mese
Sia 1) che 2) in realtà velocizzano la produzione.


Soprano ha scritto:

in realtï¿œ lo aveva fatto come provocazione, comunque essendo una persona
molto capace e molto versatile sarebbe una spreco.

 mi sembra di essere l'unico.. 
se sono commenti idioti e' preferibile non metterli, molto spesso basta 
dare i nomi con un minimo di semantica alla property o al metodo e una 
breve descrizione di cio' che fa la classe... a volte non mettere nulla 
porta dei casini assurdi tipo io avevo messo un controllo >0 su una pk e 
sono avvenuti dei casini assurdi!! :-D vabbe' che il codice era 
immondo(funzione da migliaia di righe) se quella pk se valeva 0 
succedevano alcune cose, -1 altre e poteva assumere valori negativi... 
ecco se qlc avesse commentato qlcosa non avrei fatto quella cappella 
oltretutto per risolvere non avrei perso tempo a fare reverse 
engineering. :-(
ciao
ps
sono anni che non vedo del codice da cui prendere spunto, la maggior 
parte del codice su cui a che fare e' vecchio o peggio ancora codice 
scritto da programmatori che hanno fatto delle funzioni e del ctrl+c 
ctrl+v un dogma su dei linguaggi nativi OOP... tutto cio' ha dei 
risultati abominevoli.
-- 
http://www.evilripper.net
http://www.flickr.com/photos/evilripper/

 ah gi�, tu sei nel quarto reich.
tu pensa ai tuoi venerd� pomeriggio
-- 
Soprano

 tu pensa ai tuoi venerd pomeriggio
invidiosa
--
FabMind

 Sia 1) che 2) in realt� velocizzano la produzione.
si si
penso che il senso fosse: mi pagano 8 ore per questo lavoro, io gi� ce ne
metto 8 e mezzo se non 9, se ci aggiungo anche i commenti arrivo a 10 o 11.
e le 2-3 ore che poi renderanno pi� veloce la manutenzione, le offro io.
cia'
.d
-- 
________________________________
Dan (33, MI)
33 years uninterrupted breathing
________________________________

 e le 2-3 ore che poi renderanno pi� veloce la manutenzione, le offro io.
o meglio: chi mi paga le ore di sviluppo non � disposto a pagarmi 11 ore
per un lavoro valutato 8, e in quelle 3 ore taglio il tagliabile (-> i
commenti, l'indentazione etc.)
cia' di nuo'
d.


 ma da voi i commenti nel codice si usano?
Si.
Io sono arrivato ad un equilibrio.
1. In situazioni del tipo:
//dichiaro la variabile x
//e le assegno il valore 3
int x = 3;
# itero gli elementi della lista l
# e se uno di questi è uguale a 3
# ritorno l'elemento
for x in l:
	if x == 3:
		return x
i commenti servono solo a sporcare il codice.
2. Oltre alla documentazione vera e propria per i metodi/funzioni 
pubblici che servono a far capire *cosa* fanno i metodi/funzioni, io 
cerco sempre di aggiungere un po' di commenti per far capire *come* lo 
fanno. Ovviamente i destinatari della documentazione saranno gli 
utilizzatori, mentre i destinatari dei commenti saranno i miei colleghi.
3. Per quanto riguarda la programmazione """scientifica""", oppure 
quelle porzioni di codice dove c'è parecchia 
matematica/algebra/geometria/qualsiasi-altra-cosa, cerco sempre di 
corredare il codice con un piccolo "abstract" che spieghi l'algoritmo in 
dettaglio. Idem per costrutti particolarmente "esoterici" o utilizzi 
altrettanto "esoterici" di particolari tecnologie.
Ciao,
Giulio
-- 

 commentino le interfacce di accesso ai loro moduli.
E se poi ti trovi a dover mettere mano al loro codice? Oppure siete 
organizzati in modo che ognuno lavora solo su un pezzo di codice e basta?
Ciao,
Giulio
--

 commenti, l'indentazione etc.)
ma lol senza indentazione nuoci a te e a chi ti sta intorno! :-D

 
Non c'è bisogno di usare un formato "pesante" come XML per fare questo.
Ciao  Manlio

 metto, ma mi sembra di essere l'unico..
Sempre attuale:
http://freeworld.thc.org/root/phun/unmaintain.html

 casi particolari) commentarlo per capire cosa fa.
Sono abbastanza d'accordo, con le dovute eccezioni. Da un po' di tempo
sto attento a scrivere codice leggibile, anche a scapito
dell'efficienza. Se per fare un'operazione (sporadica) ci metto 2ms in
più non se ne accorge nessuno, ma i tempi (e costi) di manutenzione
sono si abbassano e siamo tutti più contenti. Però a volte bisogna
inserire dei trucchi per risolvere qualche bug che si presenta in
condizioni particolari e rare (magari nemmeno nel proprio codice, ma
in librerie chiuse). Se non si scrive perché si fanno certe cose alla
fine chi arriva dopo non ci capisce nienete. Ogni tanto mi capita di
trovare codice di questo genere e non sapere perché sia stato messo li
e se si può togliere o meno. Diventa anche difficile ottimizzarlo e
capire come evitare il problema, in casi simili, con una diversa
organizzazione degli oggetti o con un diverso workflow.
Ciao
Mattia

 mi sembra di essere l'unico..
Di solito uso codice "parlante", ovvero nomi di variabili e metodi che 
dicono cosa sono e a cosa servono. Limito al minimo i commenti, ove 
strettamente necessario, ed evito quelli inutili e ovvi.
Mi ï¿œ capitato di leggere codice ben scritto, pulito, ben indentato, e 
non ho avuto problemi a capire cosa facesse. E mi ï¿œ capitato anche 
codice scritto col c..o, variabili chiamate a, b, c o pippo, in mezzo a 
logica ridondante, metodi chilometrici... Robe scritte da gentaglia da 
mandare a zappare.

 ma da voi i commenti nel codice si usano?
Pochissime persone li usano :-/
Stef 

 mescolando i case, eccetera, eccetera...
Questo conferma che ci vuole una supervisione ad hoc per avere
uniformità.
Ma il lavoro del supervisore dedicato costa, e probabilmente non poco.

 ma da voi i commenti nel codice si usano?
Da noi ho visto cose che ... :-)
Consulenti che facevano volutamente giri e chiamate a procedure
inutili solo per rendere il codice lungo, complesso ed ingestibile a terzi.
Alcuni commentavano tutto con un tag personalizzato, es. # xxxyyy
poi prima di andarsene lasciavano i sorgenti dopo averli processati
per mezzo di un "programmino" che toglieva determinate righe,
cosi il pgm restava pulito, ma con le procedure farlocche di cui sopra.
Ovviamente variabili e costanti con nomi da indovinello.
G X 

 "// se la chiami."
ma LOL !!!!
:-) 

 ce li metto, ma mi sembra di essere l'unico..
Io li uso, e cerco di fare documentazione fatta bene. Purtroppo , come hanno 
scritto altri, non � pi� la prassi :-(

 cosi il pgm restava pulito, ma con le procedure farlocche di cui sopra.
Ciao, non ho capito bene, me la rispeghi? :D


 
quoto !

 Sia 1) che 2) in realtà velocizzano la produzione.
premesso che  1) e 2) sono cose che so benissimo
si puo' anche dire che bisogna anche non vedere al di la' del proprio naso
per non capire che:
a) se mi chiedono espressamente di "non perdere tempo ad inserire commenti
nel codice", io, dopo averli informati di quando ad  1) e 2) ed avere
ottenuto come risposta la ripetizione "non perdere tempo ad inserire
commenti nel codice", semplicemente non inserisco commenti nel codice. 
b) Magari si velocizzera' la produzione del codice, ecc.ma...
b.1) rimettere mani sul codice porta piu' soldi che non rimettercele
b.2) chi rimette le mani sul codice e' lo stesso che ce le metteva prima, 
altrimenti il codice viene banalmente dismesso (tanto il software che viene
prodotto nel 90% dei casi non serve a niente e non interessa ne' al 
fornitore ne' al committente. In genere al primo interessa incassare dei
soldi [non importa se incassarli vendendo codice  o casse di arance]; al
secondo interessa spendere qualcosa per far vedere che lui, con il budget
assegnatogli, qualcosa ci fa )
b.3) capire cosa fa il codice non interessa a nessuno. Spesso non
interessa nemmeno che funzioni.
Ciao,
Marco.
-- 
questo articolo e` stato inviato via web dal servizio gratuito 
http://www.newsland.it/news
 segnala gli abusi ad 
ab...@newsland.it

 ..d


 modifica e se abbiamo tempo ci mettiamo anche i commenti".
Mah, che ti chiedessero di accelerare posso crederci benissimo, ma che 
per farlo ti dicessero esplicitamente di non mettere commenti � una cosa 
che mi fa ridere. Posso capire se ti avessero detto "salta i test 
automatici" o "non metterti a scrivere la documentazione", ma "non 
mettere i commenti"... francamente mi pare una fesseria. In termini di 
tempo risparmiato si parla veramente di nulla. Sicuro che non fosse 
pigrizia tua, visto che pi� che il tempo ci vuole voglia da parte del 
programmatore?

Rolando Furioso ha scritto:



In genere quando programmavo, quando
sono stato libero di decidere io ho sempre utilizzato il modello
"vecchio standard-ESA like". Ovvero per ogni funzione (o metodo di
classe),  prima del corpo della funzione inserivo qualcosa del tipo
/**************************************************************
* PROTOTIPO:
* int ReadIMSI(char *imsi, int maximsilen);
*
* PARAMETRI:
*   char *imsi     : punta all'area di memoria che dovr� 
*                    contenere l'imsi letto dalla funzione (il chiamante
*                    deve occuparsi dell'allocazione ed 
*                    eventuale deallocazione di tale zona di memoria)
*   int maximsilen : numero massimo di caratteri che possono essere scritti
*                    nella zona di memoria puntata da imsi
*
*
*  VALORE RESTITUITO: 
*  0 nel caso in cui non si siano verificati errori
* -1 nel caso di errore diverso dai seguenti
* -2 nel caso di SIM Card non inserita nel lettore
* -3 nel caso di SIM Card non italiana
* -4 nel caso di SIM Card  di un operatore diverso da TIM
* -5 nel caso di lettore di SIM Card non presente
* 
*
* DESCRIZIONE:
*
* La funzione si connette al lettore di SIM Card, legge l'IMSI della SIM,
* inserendolo nella zona di memoria puntata da imsi e restituisce un
codice * di errore (0 in caso di nessun errore). Il formato dell'imsi
* sara' del tipo MCC MNC MSIN (senza spazi tra un campo e l'altro)
* dove:
* MCC  (Mobile Country Code) e' un codice di 3 cifre (222 per SIM italiane)
* MNC  (Mobile Network Code) e' un codice di 2 cifre (01 per TIM)
* MSIN (Mobile Subscriber Identification Number) � l'identificatore
*      della SIM Card all'interno della rete del suo operatore
****************************************************************/
int ReadIMSI(char *imsi, int maximsilen)
{
...
  return ret;
}
Ciao,
Marco


 Solo un masochista pu� lavorare cos�.
per quanto d'accordo, a grandi linee, a volte penso che il tuo mondo del
lavoro sia un tantinello idealizzato.




quoto abbestia :-) personalmente ho speso pi� di un paio d'ore del mio
tempo, negli ultimi anni (percentuale bassa, eh!) ad indentare codice
altrui per capire dove mettere le mani :-))
cia'


 generare in automatico la documentazione dei metodi e delle proprietà.
Ovvio. Ma è doc che poi non usa nessuno. Si capisce al volo cosa fa quella 
funzione. 
-- 
__________________________________
Luc (36, CO)
25 years uninterrupted programming
__________________________________

 
ma guarda basterebbe fare un cazziatone della madonna al primo che non
rispetta le specifiche, gli altri si adeguerebbero.


Tu sei come quei bimbi che non capiscono quando gli spiegano come nascono
i bambini e bisogna fargli anche il disegnino ...
:-) 


purtroppo (non solo per i commenti al codice) si passa spesso da un estremo 
all'altro: nessun commento (zero !) , oppure troppi commenti ... che ti 
fanno comunque perdere del tempo a leggerli
Andrea

 Marco
Andrea 

 programmatore?
E' come dice Marco, che piaccia o meno, che faccia ridere o meno :-|
Ai consulenti 9 volte su 10 viene esplicitamente richiesto di non metterli.
ciao Nicola
--------------------------------
Inviato via 
http://arianna.libero.it/usenet/

 mi sembra di essere l'unico.. 
Buon per te