Franny's Adobe

# re: Commenti nel codice

I commenti nel codice sono utili se e solo se rispecchiano quello che veramente fa il codice e se sono più chiari del codice.

Chi mette i commenti nel codice dovrebbe anche preoccuparsi di tenerli aggiornati durante la manutenzione del codice...

Zero Policy :-)

# re: Commenti nel codice

E invece non sono d'accordo con te :)
Perche' commentare del codice, di fatto ripetendo quello che nel codice dovrebbe essere gia' scritto e poi spendere il tempo per mantenere i commenti?
Tanto vale, se il codice non e' chiaro, renderlo piu' chiaro, ed evitare i commenti.
Poi, ci sono sempre alcune situazioni nelle quali il commento non puo' essere espresso in codice (immagina un vincolo di complessita asintotica): in quel caso il commento e' necessario.

# re: Commenti nel codice

Mumble mumble. Ma se dal codice traspare già tutto, che bisogno c'è aggiungere un commento che dice la stessa cosa? :D

Se mettiamo la pena di morte per chi lo fa, rimarremmo in pochi. :asd:

# re: Commenti nel codice

In linea di massima sono d'accordo con te, ma ad esempio descrivere le responsabilità di una classe senza commenti non è sempre semplice e la loro mancanza ti costringe a guardare i dettagli interni.
La responsabilità di una classe poi è un fattore che difficilmente cambia e quindi il problema di tenere sincronizzati i commenti con la classe non è particolarmente oneroso.
A volte li uso anche per i TODO, scrivo una parte di codice che non mi viene particolarmente bene e non ho tempo di rifattorizzarla allora scrivo // TODO: ....
In questi casi quale sarebbe l'alternativa?

# re: Commenti nel codice

Un secondo...
Se stai parlando di commenti nel codice, sono stra-daccordo con te... via tutto.
Certo, ogni tanto faccio delle classi matematiche con calcoli finanziari e li i commenti ci vanno o mi perdo, ma quella spero che per te sia un eccezione ammessa.....
Ma se intendi anche quelli che dice antonio (commenti alle classi e TODO) allora ti ammazzo :D
I commenti ad ogni classe e ad ogni metodo secondo me sono _sacri_ non solo per la documentazione ma anche per chi entra nel codice e non deve girarsi la classe che ha si poche righe se scritta bene,ma è comunque del tempo perso in piu... io che utilizzo un metodo di terze parti il commento LO VOGLIO ... ed anche i TODO se il mio gruppo ha del lavoro in sospeso...
Con una condizione.. i TODO io li dato.. se vedo un TODO per piu di qualche settimana... lo notifico... se pervade, sono caXXi amari :D

# re: Commenti nel codice

Forse mi sono espresso male: nessun commento, investiamo in codice più chiaro.

# re: Commenti nel codice

I TODO mi stanno bene, non possono essere espressi in codice per ovvi motivi.
I commenti ai metodi NO. Il nome del metodo e la lista dei parametri DEVONO essere chiari da non richiedere alcun commento. Se non lo sono, il problema e' di design, non si risolve commentando.
Restano le pre condizioni, post condizioni e invarianze della classe: assert, ma meglio ancora unit test, non commenti.
Poi unit testing anche per documentare gli use case di una classe.

# Re: Commenti nel codice

sono totalmente d'accordo con te, Francesco. L'importanza di scrivere codice pulito è secondo me sottovalutato da tutti. Bisognerebbe sempre pensare che il codice che stiamo scrivendo *oggi* dovrà essere riletto e mantenuto nel futuro magari da noi, magari da altre persone ed è quindi molto importante che metodi, oggetti, variabili, classi abbiano un nome coerente con il loro ruolo assunto all'interno del progetto. E tendenzialmente, sì, anche io ho perso l'abitudine di inserire commenti, proprio perchè preferisco codice parlante che sia auto-commentante!
ciao a tutti!

# re: Commenti nel codice

Fondamentalmente sarei d'accordo anche io.
Però come dice l'altro Alessandro, i commenti alle classi e ai metodi sono comodissimi per la generazione della documentazione.

Personalmente commento ogni classe e ogni metodo e ogni tanto commento anche il codice, sopratutto nei punti in cui so già che servirà (anche per me stesso).

# re: Commenti nel codice

Il problema è che se commenti anche i metodi e poi questi cambiano nel "comportamento"... devi nuovamente andare a ritoccare pure i commenti...

# re: Commenti nel codice

Io e Igor sulla stessa lunghezza d'onda :)
Per quanto riguarda la documentazione, per me il codice e' sacro e lui e' il mio primo obiettivo: ho visto codice di classi con il 70% di linee come commenti. Totalmente illeggibile.
Mi puo' stare anche bene una descrizione del metodo in un file di documentazione (scritto da altri, non da me), ma fuori dalla code base.
A chi commenta spesso, consiglierei di provare una settimana "comment free": ogni volta che sente la necessita' di scrivere un commento guardi il codice e cerchi di capire se puo' essere scritto meglio.

Io sono ormai quasi totalmente comment-free e la mia qualita' della vita e' migliorata, sto anche perdendo la pancetta :)

# re: No Comment

Non perderai mai la pancetta :D
Comunque probabilmente abbiamo progetti con target diversi. Se io scrivo una DLL di utilità e devo spezzare il commento fuori dalla CodeBase, poi me li vieni a consuntivare te quelle due settimane per scrivere la documentazione che invece con NDoc sono gratuite.
Ripeto, senza _NULLA_ togliere al fatto che i metodi _devono_ essere parlanti e i parametri pure. Ma pensa a cosa succederebbe se nel framework non ci fosse la documentazione sull'intellisense, e non mi venire a dire che i metodi non sono parlanti....

# re: No Comment

Ale, quelle due settimane per scrivere la documentazione sei sicuro di non perderle per una code base piu' "cluttered" di quanto necessario per via dei commenti?
E il tempo che perdi a tenere quei commenti in sincronia col codice durante lo sviluppo, il refactoring, il mantenimento del codice.

# re: No Comment

"Io sono ormai quasi totalmente comment-free e la mia qualita' della vita e' migliorata, sto anche perdendo la pancetta :)"

la tua probabilmente sì visto che non penso esista uno sviluppatore che ama scrivere commenti :) bisogna vedere cosa ne pensa chi poi dovrà prendere in mano il codice. Io sono daccordo con chi dice di commentare al minimo le classi e i metodi in particolare quelli pubblici. Non serve certo scrivere un tema. Inoltre credo che quello che oggi ci sembra semplice e chiaro perchè è un mese che sviluppiamo quel progetto e conosciamo a memoria le variabili, i metodi, la logica che ci sta dietro non lo sia altrettanto fra un anno.

Non sottoscrivo quindi la Zero Policy :-)

# re: No Comment

Chi deve prendere in mano il mio codice pensa che sia fra i piu' leggibili e "semplici" in azienda.
E molto di questo risultato e' dovuto proprio al fatto che non scrivo commenti: se un pezzo di codice non e' chiaro semplicemente lo riscrivo.
Fra le altre pratiche che uso c'e' il far leggere il mio codice agli artisti per sapere se capiscono quello che voglio esprimere: quando non ci riescono, riscrivo.
Fra un anno leggero' codice che, per la maggior parte, si legge come fosse inglese e non e' insozzato da commenti :)
L'ultimo commento che ho scritto credo sia due mesi fa per documentare un workaround di un bug dell'XDK.

Zero Policy

# re: No Comment

Sono sostanzialmente d'accordo con quello che dici, anche io ho l'abitudine di far leggere il mio codice a programmatori Junior (visto che dove lavoro non abbiamo artisti). Vorrei aggiungere che ci sono delle situazioni in cui scrivo una classe e non riesco a trovare un nome sufficientemente chiaro per comprenderne al volo la sua responsabilità, oppure la scadenza è pressante e non ne ho il tempo, a questo punto cosa faresti?
Oppure nel caso delle eccezioni, supponiamo che hai un interfaccia con un metodo che in caso di errore ci si aspetta una certa exception cosa faresti? Come fai a dare un nome che spieghi ciò?

# re: No Comment

Antonio, riguardo al nome di una classe (o interfaccia o metodo o variabile), io sono convintissimo che quando non riesco a trovare un buon nome, e' perche' non mi e' chiaro il suo scopo o le sue responsabilita' e c'e' qualcosa di sbagliato nel mio design. Mi fermo e cerco di chiarirmi le idee e il design.
Se la scadenza e' pressante, non si rifattorizza, un bel TODO (datato come fa Alessandro) grosso come una casa e si chiude la milestone.
Riguardo le eccezioni, purtroppo sono bannate dal gamedev e non ho quasi esperienza a riguardo, ma io documentereri un metodo che restituisce un'eccezione con un bel test: chiaro, conciso, inequivocabile e se rifattorizzi il metodo e' ancora li' a controllare se quel metodo restituisce l'eccezione quando deve.

# re: No Comment

# define
IGNORE_MISSING_DX_FILE // ignore missing file

qua mi son piegato in due, PURO GENIO :D

# re: No Comment

Ciao a tutti, discussione molto interessante.
Quelli indicati da Francesco nel post sono chiaramente casi estremi.. e come tali perfettamente criticabili.
In generale la mia opinione è che sia sempre salutare che ci siano commenti. Ovviamente devono essere usati in modo intelligente. Personalmente odio quando mi trovo a lavorare su del codice senza neanche un commento e non condivido la tendenza di molti a considerare "più pulito" un codice con "senza righe verdi". Sono d'accordo con Francesco quando parla di unit test ma credo che siano 2 discorsi indipendenti.. Bisogna tenere conto che un metodo può essere intrinsecamente chiaro per quello che fa leggendone il codice, ma in un ottica di un progetto medio grande quando la funzione è chiamata? da chi? in quali condizioni? è thread safe? Non credete che queste informazioni sia meglio averle in linguaggio naturale in poche righe di commento? Neanche io quindi sottoscrivo la Zero Policy. Ciao a tutti! Michele

# re: No Comment

La condizione di "thread safety", se non è rappresentabile tramite il codice, va giustamente inserita come commento.

Comunque non mi sembra che Francesco abbia scritto che non bisogna mettere del tutto dei commenti, ma che bisogna metterli soltanto se si devono trasmettere informazioni che non si possono rappresentare tramite codice.

# re: No Comment

Ciao Michele. No, penso che quelle informazioni che hai indicato siano meglio espresse in codice in maniera chiara. Ovviamente una condizione di thread safety non puo' essere espressa in codice (magari nel nome del metodo, ma non sempre e' possibile) quindi il commento ci puo' stare. Non sono contro ogni commento, solo contro tutti i commenti che possono espressi in codice: il 99.9% :)

Credo che il punto della questione sia la chiarezza del codice che si sta scrivendo: se il codice si riesce a leggere come inglese, e' chiaro, stringato e autocommentante (sottolineo l'autocommentante), non ha mai bisogno di commenti, sarebbero inutile ripetizione. Se il codice non e' autocommentante, allora la soluzione del problema e' cambiare il codice, non commentarlo.
Un giorno o l'altro provo a bloggare del codice che reputo autocommentante per illustrare meglio il concetto.

# re: No Comment

Non postare il mio allora. :asd:

# re: No Comment

Credo che della stessa razza fanno parte, oggi, i #region di C#.

Esempio:

#region Repeating Function

/// <summary>
/// Ripete costantemente l'invio dei dati al concentratore o al web service
/// </summary>
protected override void RepeatingFunction()

# re: No Comment

IMHO i commenti devono esprimere il "perché", non il "come".
Per il "come" il codice *deve* essere autoesplicativo, ma nessun codice, nemmeno il meglio scritto, può esprimere le motivazioni di una certa scelta (e qui il commento è d'obbligo a meno che il "perché" sia ovvio)

# re: No Comment

Sono d'accordo con Matteo, leggendo del codice ben scritto si capisce cosa fa senza bisogno di commenti, ma non è detto che si capisca perche fa cosi.
In quel caso una piccola nota ci puo stare imho...

# re: No Comment

Come al solito sto al 100% d'accordo con Cesare e Francesco :P

Io programmo praticamente senza commenti. Sicuramente non commento i metodi o il codice.

Scrivo commenti solo per spiegare alcune scelte tipo: implemento temporaneamente un metodo in maniera semplice ed inefficiente per poter andare avanti con lo sviluppo senza overngineerizzare ora che non serve.

Ma onestamente dovrebbe essere una cosa ovvia se lavorassimo in XP.. Visto che non lavoriamo in XP li scrivo giusto per evitare che la gente venga a rompere i maroni con "we fighetta il metodo qui e` ultra inefficiente non cache coherent e non e` abbastanza illegibile per passare il l337 hax00r uber n3rd approval!" visto che, come molti di voi sanno, nella gamedev e` pieno di gente del genere...

Giusto una nota: Odio con tutto il mio cuore il codice disabilitato tramite commenti perche` "magari in futuro servira`", cazzo quando lo vedo mi prende il raptus omicida!! :P

Un'ultima cosa. Secondo me se si scrive una libreria prima di fare deploy del progetto scrivere commenti ai metodi (non nella codebase pero`) e` un must. A parte il vantaggio di avere il CHM/PDF/JPG/MP3/DIVX contenente una descrizione del sistema, spesso nomi possono essere difficili da trovare senza scrivere 500 caratteri di roba e una descrizione delle classi giusto per evitare malintesi e` necessaria.

Dopotutto non ditemi che per lavorare in DX / XNA / XDK non aprite mai il CHM eh :P

# Free porn.

Asian porn. Porn inspector. Home made porn. Porn. Free porn. Simpsons porn.

# How people abuse ultram er.

Ultram tramadol. Ingredients for ultram. Ultram. Ultram online. Ultram er tablets.

# Animal sex.

Animal sex videos. Free animal sex videos free. Sex animal.

# Incest sex stories.

Free incest sex stories. Free erotic incest stories. Mother son incest stories mother. Incest stories mother son incest. Mom son incest stories. Incest stories.

# Sex animal.

Animal sex movies. Free animal sex. Animal having sex. Animal sex stories free. Animal sex pic. Animal sex free. Women and animal sex. Animal sex. Farm animal sex.

# Gallery of paris hilton.

Paris hilton sex tape. Britney spears and paris hilton. Brittney spears and paris hilton. Paris hilton. Free paris hilton sex tape. Paris hilton nude.

# Free incest pic.

Incest thumbs.

# Vicodin withdrawal symtoms.

Vicodin user message board. Vicodin side effects. Vicodin. Buy vicodin without script.

# Citalopram side effects.

Citalopram.

# Citalopram.

Citalopram hbr. Citalopram hydrobromide. Citalopram.

# Rogaine.

Rogaine direct. Rogaine beard growth. Rogaine. Rogaine for women. Rogaine foam. Rogaine side effects. Side effects rogaine.

# Valtrex and pregnancy.

How does valtrex affect warafin. Valtrex.