[Programmazione Object Oriented] Buone norme..

Originariamente inviato da fek

Altamente discutibile

"I commenti sono un deodorante per il codice. Meglio eliminare la puzza."

beh può essere come dici tu, ma se non fosse così? me lo puoi dimostrare?

innanzitutto non voglio certo commentare qualcosa che si commenta da se. mettere commenti e crearsi sopratutto una documentazione serve alla manutenzione di grandi applicazioni, serve a te e serve ai colleghi. naturalmente deve essere sempre consistente con la realtà, univoca e precisa. è una cosa che al momento della creazione ti potrebbe stressare ma farla ma credimi e molto probabile che in fututro sia un ottimo incentivo a risparmiare tempo e nervi

[fek]

Originariamente inviato da trias

beh può essere come dici tu, ma se non fosse così? me lo puoi dimostrare?

innanzitutto non voglio certo commentare qualcosa che si commenta da se. mettere commenti e crearsi sopratutto una documentazione serve alla manutenzione di grandi applicazioni, serve a te e serve ai colleghi. naturalmente deve essere sempre consistente con la realtà, univoca e precisa. è una cosa che al momento della creazione ti potrebbe stressare ma farla ma credimi e molto probabile che in fututro sia un ottimo incentivo a risparmiare tempo e nervi

Si', posso dimostrarti quello che dico

Versione numero 1:

[C++]

                // ...

                // Send all directional lights to the GPU

		for (s32 i = 0; i < ret_num_directional_lights; ++i)
		{
                        // Get Directional light from the lighting manager and cast it
			const CLightingManager::CDirectionalLight* p_directional_light = STATIC_CAST(const CLightingManager::CDirectionalLight*,light_list[ i ]);

                        // Get direction from the light
			CVector3 direction		= p_directional_light->GetDirection();

                         // Get light colour
			CRGBFloatColour colour	= p_directional_light->GetColour();

			// Send direction constant to the GPU
CShaderManager::SetPSConstantElement(BIND_PS_CONSTANT(g_DirectionalLightDirection),	element, direction);

                        // Send colour to the GPU			
CShaderManager::SetPSConstantElement(BIND_PS_CONSTANT(g_DirectionalLightColor),	element, CVector3(colour.R, colour.G, colour.B));

                        // next element
			element++;
		}

                // ...

Bel codice, ben commentato vero? No, fa schifo.

Guarda questa versione:

[C++]

                // ...

                SendDirectionalLightsToTheGPU();

Il nome del metodo si auto commenta.

E poi l'implementazione:

		for (s32 i = 0; i < ret_num_directional_lights; ++i)
		{
			const CLightingManager::CDirectionalLight* light = GetDirectionaLight(i);

                        light.SendDirectionToTheGPU();
                        light.SendColourToTheGPU();

			light.NextElement();
		}

Neppure un commento, ma il codice si commenta da solo.

Regola generale: Non si commenta mai cio' che puo' essere espresso in codice, si commenta solo cio' che non puo' essere espresso in codice.

Quello che il codice fa puo' essere espresso dal codice stesso, che e' la migliore e piu' aggiornata documentazione di se' stesso. Bisogna commentare ad esempio assunzioni che si fanno su un algoritmo ("Questo codice funziona se l'input e' di questo tipo"), oppure post e pre condizioni che non possono essere espresse da assert o da test (rarissimo).

Sostanzilamente, se il codice e' chiaro e ben scritto non c'e' quasi mai necessita' di commentare. Se il codice e' scritto male, la soluzione non e' commentarlo (il deodorante), ma riscriverlo in maniera comprensibile (eliminare la puzza).

"An heuristic we follow is that whenever we feel the need to comment something, we write a method instead" - Martin Fowler

Non commentare, riscrivi il codice, il tuo programma e i tuoi colleghi ti ringrazieranno e tu risparmierai un sacco di tempo

E per chi e' curioso, Martin aggiunge:

"Don't worry, we aren't saying that people shouldn't write comments. In our olfactory analogy,comments aren't a bad smell; indeed they are a sweet smell.The reason we mention comments here is that comments often are used as a deodorant. It's surprising how often you look at thickly commented code and notice that the comments are there because the code is bad. ......Our first action is to remove the bad smells by refactoring. When we're finished, we often find that the comments are superfluous."

Originariamente inviato da fek

Neppure un commento, ma il codice si commenta da solo.

Regola generale: Non si commenta mai cio' che puo' essere espresso in codice, si commenta solo cio' che non puo' essere espresso in codice.

Quello che il codice fa puo' essere espresso dal codice stesso, che e' la migliore e piu' aggiornata documentazione di se' stesso. Bisogna commentare ad esempio assunzioni che si fanno su un algoritmo ("Questo codice funziona se l'input e' di questo tipo"), oppure post e pre condizioni che non possono essere espresse da assert o da test (rarissimo).

da un punto di vista globale una cosa testimonia sempre la sua funzione. diciamo pure che è una proprietà intrinseca, e su quel che dici non ci piove. dal puto di vista "del comune mortale perso nell'immenso di tutto del codice" le cose che si riescono a capire subito certamente è inutile commentare e questo l'ho anche detto. infatti ho detto che il commento ci voleva in caso (eccezione che conferma la regola) il codice lì è un po' debole ma va bene

Sostanzilamente, se il codice e' chiaro e ben scritto non c'e' quasi mai necessita' di commentare. Se il codice e' scritto male, la soluzione non e' commentarlo (il deodorante), ma riscriverlo in maniera comprensibile (eliminare la puzza).

"An heuristic we follow is that whenever we feel the need to comment something, we write a method instead" - Martin Fowler

Non commentare, riscrivi il codice, il tuo programma e i tuoi colleghi ti ringrazieranno e tu risparmierai un sacco di tempo

ma, se hai tempo si, se non sei portato a programmare e scrivere codice perfetto lasciaci stare, oppure trova un compromesso fai una puzzetta lieve qui e li se vedi che nell'intimo della tua classe te lo puoi permettere

[fek]

Originariamente inviato da trias

da un punto di vista globale una cosa testimonia sempre la sua funzione. diciamo pure che è una proprietà intrinseca, e su quel che dici non ci piove. dal puto di vista "del comune mortale perso nell'immenso di tutto del codice" le cose che si riescono a capire subito certamente è inutile commentare e questo l'ho anche detto. infatti ho detto che il commento ci voleva in caso (eccezione che conferma la regola) il codice lì è un po' debole ma va bene

E' proprio questa la mentalita' sbagliata, dire che il codice un po' debole ma va anche bene, quindi se proprio non si capisce, ci si mette un commento.

No, non funziona cosi'. Il codice un po' debole non va commentato, va riscritto e reso chiaro, perche' tutto il codice deve autocommentarsi. Le eccezioni non devono esserci. E' la sindrome della "broken window".

ma, se hai tempo si, se non sei portato a programmare e scrivere codice perfetto lasciaci stare, oppure trova un compromesso fai una puzzetta lieve qui e li se vedi che nell'intimo della tua classe te lo puoi permettere

Se hai tempo lo fai, se non hai tempo lo fai ugualmente. Se non si e' capaci a scrivere codice leggibile (non perfetto, perche' non esiste), si impara o si cambia mestiere. E' pieno di mestieri in giro

Ron Jeffries descrive questo concetto con una metafora divertente: chiama il codice scritto male "coding debt", un debito che si accumula ogni volta che un pezzo di codice e' lasciato li', anche se dovrebbe essere rifattorizzato, e il debito prima o poi viene ripagato in termini di tempo e soldi, fino a che non si accumulano talmente tanti debiti che si va in banca rotta e il progetto non puo' piu' essere concluso.

Si puo' accumulare qualche debito per un breve periodo (magari vicini ad una milestone), ma poi il debito va ripagato subito, e il codice rifattorizzato, riscritto, corretto, semplificato. Le puzzette nella code base devono sparire non appena possibile, non e' una perdita di tempo, e' un guadagno di tempo enorme nel lungo periodo.

Non per altro svariati studi mettono in evidenza come un buon programmatore costi molto meno all'azienda di un programmatore scarso.

aiaiaiaiaiaiaiaaiaiaia vabene scomunichiamo il "//" usato ogni tanto ma non mi dirai che HALFLIFE2 si auto commenta da solo appena guardi un metodo!!!!!

[fek]

Originariamente inviato da trias

aiaiaiaiaiaiaiaaiaiaia vabene scomunichiamo il "//" usato ogni tanto ma non mi dirai che HALFLIFE2 si auto commenta da solo appena guardi un metodo!!!!!

Diamonds si commenta praticamente da solo

[shang84]

Originariamente inviato da fek

In futuro se il tuo collega deve solo usare la classe, non deve conoscerne il funzionamento interno, non gli serve sapere che il costruttore chiama i metodi privati della classe in un certo ordine. Il contratto della tua classe impone che a seguiro della creazione dell'oggetto (quindi della chiamata al costruttore), l'oggetto e' creato correttamente ed e' usabile, altrimenti avrebbe sollevato un'eccezione.

Non devi neppure commentarlo.

Discorso leggermente diverso se il tuo collega deve "mantenere", quindi modificare la classe che hai scritto tu, quindi deve sapere che il costruttore deve chiamare due metodi in un certo ordine per la corretta creazione della classe.

Come fare?

Una soluzione potrebbe essere commentare il codice, qualcosa del tipo:

[Java]

MyClass()
{
  // ...
  // method1() dev'essere chiamato prima di chiamare method2()

  method1();
  method2();
  // ...
}

Male, questo codice viola un principio chiamato DRY (Dont Repeat Yourself), esprimi la stessa informazione sull'ordine di chiamata dei metodi in due posti differenti: il commento e il codice. Se cambi l'ordine dei metodi devi anche modificare il commento. Di solito quando per modificare qualcosa, devi anche modificare qualcos'altro, sei di fronte ad un problema che va risolto.

Vediamo questa versione:

[Java]

MyClass()
{
  // ...

  firstStepOfInitialisation();
  secondStepOfInitialisation();

  // ...
}

Gia' molto meglio: i nomi dei due metodi chiariscono immediatamente al tuo collega l'ordine di chiamata dei metodi, senza bisogno di alcun commento o di alcuna documentazione. Si dice che il codice si auto documenta.

Che succede se il mio collega e' magari un po' stanco, ha fretta e modifica questo codice in questa maniera?

[Java]

MyClass()
{
  // ...

  firstStepOfInitialisation();

  // ...
}

Ooops, la seconda chiamata e' sparita, l'oggetto non e' creato completamente e magari scopri bug di fronte al tuo cliente durante la dimostrazione del programma. Non e' una bella situazione.

Il problema si risolve testato automaticamente che il primo metodo e' chiamato prima del secondo. Ma questo e' un altro argomento.

Leggo solo ora questo post in quanto ci si stava rispondendo contemporaneamente, comunque ottimo consiglio! oltre ai commenti (senza ripetermi!) userò nomi di metodi altamente significativi che indichino l'ordine di chiamata.

Thnks!

[fek]

Originariamente inviato da shang84

Leggo solo ora questo post in quanto ci si stava rispondendo contemporaneamente, comunque ottimo consiglio! oltre ai commenti (senza ripetermi!) userò nomi di metodi altamente significativi che indichino l'ordine di chiamata.

Thnks!

Vedrai che con un po' di pratica non ti serviranno neppure piu' i commenti.

non hai risposto alla mia domanda, hl2 ha 7 mila file di semplice codice che non si autocommenta affatto senza un minimo supporto di documentazione. tu mi puoi anche dire che si capisce cosa fa un metodo localmente i una classe ma non puoi pretendere che uno nuovo del progetto capisca subito tutto-e-cosa quel pezzo di codice comporta globalmente nel sistema...

[shang84]

Originariamente inviato da fek

Vedrai che con un po' di pratica non ti serviranno neppure piu' i commenti.

Originariamente inviato da trias

non hai risposto alla mia domanda, hl2 ha 7 mila file di semplice codice che non si autocommenta affatto senza un minimo supporto di documentazione. tu mi puoi anche dire che si capisce cosa fa un metodo localmente i una classe ma non puoi pretendere che uno nuovo del progetto capisca subito tutto-e-cosa quel pezzo di codice comporta globalmente nel sistema...

E qui cerco di fare da mediatore:

i commenti li metterò sempre perchè ci sarà sempre il programmatore inesperto che ha bisogno di farsi le ossa e che per iniziare a lavorare e a capire il mio codice ha bisogno di commenti.

Hai mai lavorato a un progetto scientifico di ricerca in cui si implementano algoritmi di difficile comprensione?*

*non immediati e che implichino una conoscenza approfondita di una materia (che sia riguardo la fisica, la biologia, la chimica, l'economica ..)

Be ti assicuro che in questi casi se il programmatore che ha scritto il codice su cui devi lavorare ha aggiunto qualche commento si capisce ben prima la logica del programma senza rompere e far perdere tempo ai Biologi, Economi o chi altri con cui lavori per capire il codice.

Quindi la mia teoria è:

un codice va ben commentato,
troppi commenti vanno evitati se si può fare codice autoesplicativo (con nomi significativo), ma un minimo di commenti (ben ordinati e spiegati) ci vuole.


PS: si lavora in team! mai da soli! E un team non può essere composto da super-programmatori sempre esperti - in un team ci può essere sempre chi ha bisogno di farsi le ossa. Altrimenti come fai ad imparare?

[fek]

Originariamente inviato da trias

non hai risposto alla mia domanda, hl2 ha 7 mila file di semplice codice che non si autocommenta affatto senza un minimo supporto di documentazione. tu mi puoi anche dire che si capisce cosa fa un metodo localmente i una classe ma non puoi pretendere che uno nuovo del progetto capisca subito tutto-e-cosa quel pezzo di codice comporta globalmente nel sistema...

Ti ho risposto alla domanda. Il codice di Diamonds si auto commenta praticamente tutto, aprilo e guardalo. Se non ti e' chiara l'interfaccia di una classe, ci sono i test relativi che la documentano. Se non ti sono chiare le relazioni fra le varie classi, anche qui ci sono i test che le documentano.

Se qualcosa ancora non e' chiaro, diccelo che semplifichiamo e chiariamo il codice.

Se il codice di HL2 non si auto commenta non e' un problema mio ma di chi lo ha scritto e lo deve mantenere.

[fek]

Originariamente inviato da shang84

Hai mai lavorato a un progetto scientifico di ricerca in cui si implementano algoritmi di difficile comprensione?*

No, ma ho lavorato su code base di qualche milione di righe di codice e so che vuol dire avere codice mal scritto e doverlo studiare
Quando hai di fronte un metodo da 1.500 righe, non c'e' commento che tenga. Non si capisce comunque nulla.

un codice va ben commentato,
troppi commenti vanno evitati se si può fare codice autoesplicativo (con nomi significativo), ma un minimo di commenti (ben ordinati e spiegati) ci vuole.

Il codice deve auto commentarsi. Codice ben scritto non ha alcun bisogno di commenti.

PS: si lavora in team! mai da soli! E un team non può essere composto da super-programmatori sempre esperti - in un team ci può essere sempre chi ha bisogno di farsi le ossa. Altrimenti come fai ad imparare?

Pair Programming e Peer Review

I programmatori inesperti imparano leggendo codice ben scritto, programmando con chi e' piu' esperto. Tutto possiamo dire di Diamonds ma non che e' composto da super programmatori sempre esperti, anzi, la maggior parte neppure aveva mai visto Java prima (me compreso). Eppure non abbiamo bisogno di commenti, scriviamo codice pulito ed il tempo di ingresso nel progetto e' praticamente nullo.

[shang84]

Ma dei commenti sull'utilizzo delle classi all'interno di un programma ci vogliono.
O di che cosa fa un certo metodo.

Non puoi scrivere metodochecalcolaloscorediunospettrodopoaverfattoildenoisingdeisegnali()


cmq sono d'accordo sulla autoesplicazione del codice (quando possiblie) ma non voglio ora farne una questione "politica".. ora devo andare.

Ciao

[fek]

Originariamente inviato da shang84

Ma dei commenti sull'utilizzo delle classi all'interno di un programma ci vogliono.
O di che cosa fa un certo metodo.

Non puoi scrivere metodochecalcolaloscorediunospettrodopoaverfattoildenoisingdeisegnali()

Ci sono i test automatici per quello

Un test ti documenta in maniera inequivocabile il significato e l'uso di un metodo in una classe, oppure la relazione di una classe con un altra. E non solo lo documenta, controlla anche attivamente che i contratti che tu stabilisci e documenti siano effettivamente rispettati dal codice. E lo fa decine di volta al giorno ed e' sempre in sincronia col codice per definizione.

La documentazione e i commenti non sono sempre in sincronia col codice, non controllano attivamente che quello che e' scritto nel commento sia effettivamente vero, non documentano in maniera inequivocabile. Sono una duplicazione di concetti gia' espressi, duplicazione che va mantenuta a costo di tempo e denaro. Non c'e' nulla di peggio di un commento sbagliato, non in sincronia col codice.

[fek]

Ripeto, guardate il codice di Diamonds, e' disponibile a tutti e non c'e' un commento che sia uno

E poi ditemi se non e' piu' che chiaro.

[jappilas]

Originariamente inviato da franksisca

Lo standard di progettazione di un software è questo(molto semplificato) diagramma UML,relazione e manuali, Implementazione, testing e pubblicazione.

a parte che per quanto ne so, SW _solution_development_design_model != (coding standard || naming_convention) , cioè è diverso e prescinde

ma una domanda: se anche progettassi la tua soluzione informatica tramite UML, modelleresti le strutture dati sul problema concreto, o, avresti un approccio generale al problema, introducendo classi astratte, implemetandone estensivamente i metodi per farle apparire "complete" e "general purpose", anche se non utili e propedeutici ad un problema, che avrebbe magari preferito una classe meno general purpose e più efficiente?

voglio dire, UML non vuol dire strutturare le classi in modo non mirato...

Originariamente inviato da fek

"I commenti sono un deodorante per il codice. Meglio eliminare la puzza."

i tuoi trattati sul code design e le code smells... dolci ricordi

Originariamente inviato da fek

Ripeto, guardate il codice di Diamonds, e' disponibile a tutti e non c'e' un commento che sia uno E poi ditemi se non e' piu' che chiaro.

sono mancato per un po' di tempo, non avevo ancora installato Eclipse e ho scaricato l' SVN solo adesso ma... miracolo! mi ci raccapezzo! (cioè, devo solo capire l' organigramma delle stories e cosa si voleva ottenere volta per volta )
comunque è vero, l' optimum a cui si deve tendere è programmare "in inglese", facendo in modo che gli statement sembrino frasi di senso compiuto

[jappilas]

Originariamente inviato da shang84

Ma dei commenti sull'utilizzo delle classi all'interno di un programma ci vogliono.
O di che cosa fa un certo metodo.

Non puoi scrivere metodochecalcolaloscorediunospettrodopoaverfattoildenoisingdeisegnali()

IMHO, solo una categoria di codice, tra quello scritto ex novo (quando si deve riciclare codice altrui è un altro paio di maniche, ma quando si ha il controllo totale non ci sono scusanti) , può permettersi di non essere autoesplicativo (ma allora non ci si potrà esimere dal commentarlo più che bene): quello che presenta un più o meno ingente disaccoppiamento tra funzione, algoritmo e implementazione -
ad esempio, qualora esaminando una funzione e notando che questa va a leggere da una tabella di valori o faccia somme e shift a sinistra (CORDIC), non avessi modo di rendermi conto che si sta calcolando un sin()...
ma qui siamo nel regno delle ottimizzazioni

[cover]

Originariamente inviato da fek

I programmatori inesperti imparano leggendo codice ben scritto, programmando con chi e' piu' esperto. Tutto possiamo dire di Diamonds ma non che e' composto da super programmatori sempre esperti, anzi, la maggior parte neppure aveva mai visto Java prima (me compreso). Eppure non abbiamo bisogno di commenti, scriviamo codice pulito ed il tempo di ingresso nel progetto e' praticamente nullo.

Io sono un esempio pratico di programmatore inesperto che guardando diamonds ci capisce tutto (ok, ok...sto scherzando, la parte dell'opengl l'ho guardata , ma lì è perchè non conosco le librerie), e conoscenza generale nella programmazione non dico sia pari a nulla, ma comunque oltre ai semplici programmini (calcolatrice in vb, notepad e altre cose simili) non ha mai fatto. Però già il fatto di esser riuscito a fare un task del progetto con relativi test e implementazione scritti da 0 mi soddisfa ^^
Fek, penso che il tuo esempio dei commenti lo farò leggere a qualcuno che conosco (stai pensando a qualche mio prof? ma...come hai fatto? ), visto che a parte code del tipo x++ il resto lo vuole commentato
Ehi fek, a quando il tuo libro in tutte le migliori biblioteche?

Originariamente inviato da jappilas

IMHO, solo una categoria di codice, tra quello scritto ex novo (quando si deve riciclare codice altrui è un altro paio di maniche, ma quando si ha il controllo totale non ci sono scusanti) , può permettersi di non essere autoesplicativo (ma allora non ci si potrà esimere dal commentarlo più che bene): quello che presenta un più o meno ingente disaccoppiamento tra funzione, algoritmo e implementazione -
ad esempio, qualora esaminando una funzione e notando che questa va a leggere da una tabella di valori o faccia somme e shift a sinistra (CORDIC), non avessi modo di rendermi conto che si sta calcolando un sin()...
ma qui siamo nel regno delle ottimizzazioni

awwww mi viene il mal di pancia

Originariamente inviato da fek

Ti ho risposto alla domanda. Il codice di Diamonds si auto commenta praticamente tutto, aprilo e guardalo. Se non ti e' chiara l'interfaccia di una classe, ci sono i test relativi che la documentano. Se non ti sono chiare le relazioni fra le varie classi, anche qui ci sono i test che le documentano.

Se qualcosa ancora non e' chiaro, diccelo che semplifichiamo e chiariamo il codice.

Se il codice di HL2 non si auto commenta non e' un problema mio ma di chi lo ha scritto e lo deve mantenere.

ok mi hai convinto in parte, se ci sono meccanismi automatici che permettono di estrarre la conoscenza necessaria dal codice stesso ben vengano...