Nello spirito di coerenza, è accettabile commentare tutto allo stesso modo? [chiuso]

0

La coerenza è qualcosa che apprezzo (ad un livello perfezionista OCD per essere onesto). Posso vivere senza scrivere nessun commento e concentrarmi sulla produzione di codice buono, rifatto, leggibile - o, se devo commentare, preferirei decidere un modello di commento molto specifico e commentare in quel modo in tutto il codice in modo coerente, non solo per spiegare alcune parti complicate.

Commenta tutto come descritto o non lo è affatto, ma non "da qualche parte nel mezzo" una pratica di codifica accettabile?

    
posta Viziionary 19.09.2015 - 03:18
fonte

3 risposte

4

Al mio primo vero lavoro sono stato assunto da un paio di OCDers che volevano che scrivessi sempre codice come questo:

/* comment describing what the next few lines do */
a line of code
a line of code
a line of code

/* comment describing what the next few lines do */
a line of code
a line of code
a line of code

ecc.

L'idea era che dovrebbe essere possibile ottenere una comprensione relativamente buona di ciò che fa il codice leggendo i commenti, ignorando completamente il codice reale. Perché ciò funzioni, c'erano alcune regole aggiuntive, ad esempio che i commenti sul codice dovevano sempre iniziare con un verbo, ecc.

Quindi, ho imparato a programmare in questo modo, e ho pensato che fosse bello. Sfortunatamente, questo ha portato a molte situazioni WTF, come la seguente:

function int foo( int x )
{
    /* preconditions */
    assert x > 0;

    /* change state */
    this.x = x;

    /* return same value to enable fluent style */
    return x;
}

Ai lavori che ho fatto dopo, la gente ha guardato il mio stile di codifica e non ha detto nulla per evitare di insultarmi, o, se si sentivano abbastanza amichevoli da darmi dei consigli, mi hanno detto che questo stile di commento era deficiente .

Inoltre, altri programmatori non si sono sentiti in alcun modo obbligati a seguire il mio modo di commentare, quindi quando qualcun altro ha modificato il mio codice, il loro totale disprezzo nei confronti dei miei commenti era spesso equivalente a sovversione, ad esempio:

    /* return same value to enable fluent style */
    notifyTheWorldThatXHasChanged();
    return x;

Quindi, nella mia esperienza, nella maggior parte dei luoghi di lavoro là fuori, questo stile di commenti tende a essere disapprovato.

Il mio consiglio sarebbe quello di scrivere un codice di auto-documentazione e seguire la regola "commenti minimi", il che significa solo aggiungere un commento se è necessario. I commenti nel codice dovrebbero essere necessari solo in circostanze eccezionali e la loro presenza dovrebbe avvertire il lettore che sta succedendo qualcosa di straordinario.

Quando è necessario un commento? Quando una lettura ragionevolmente attenta del codice non rivela ciò che fa il codice, o perché una determinata cosa viene eseguita in un modo particolare.

Cosa dovrebbe essere considerato una lettura del codice ragionevolmente attenta? È quando focalizzi tutta la tua attenzione sulla lettura del codice, con un sincero obiettivo di capire cosa lo fa, ma tu credi che il codice faccia effettivamente quello che sembra mirare a fare, quindi in realtà non stai attraversando il dolore di eseguire il codice nella tua mente, cercando di capire cosa veramente fa, come se il codice avesse secondi fini . Dovresti farlo solo quando esegui il debug del codice.

Ovviamente, il trucco è scrivere quel codice elusivo di auto-documentazione che, quando lo guardi, diventa immediatamente ovvio. Mi piace credere che quello che facciamo sia per lo più una scienza, ma questo particolare piccolo sembra più un'arte per me. Un'arte che vale la pena di padroneggiare.

    
risposta data 19.09.2015 - 11:31
fonte
3

Accettabile a chi?

Se il tuo capo ti licenzierà perché sei stato incoerente nei tuoi commenti, forse non è accettabile. Se il tuo capo ti licenzia perché sei andato al DOC con i commenti anziché spedire, forse non è accettabile.

La coerenza nei commenti è ... Ok, credo. La coerenza nel codice è migliore. La coerenza nei test è migliore. La coerenza nel processo è migliore. E i buoni commenti, il buon codice, il buon processo e i buoni test sono migliori delle cose decisamente cattive.

Quindi la domanda se è accettabile o no è piuttosto discutibile, perché a nessuno importa molto.

    
risposta data 19.09.2015 - 03:28
fonte
-5

Innanzitutto, come ha scritto @Telastyn, la tua domanda è piuttosto soggettiva .. Inoltre, sembra che il problema non sia con il tuo capo / azienda / team / standard mondiali, ma internamente il tuo.

In quanto tale, posso solo dare i miei due centesimi (leggi: opinione) sull'argomento.

Questa risposta è stata pesantemente modificata dopo che ero stato educato (dai gentili utenti) sul merito del non commentare. Mai. In ogni situazione in qualsiasi lingua in qualsiasi strumento. Anche se si trova sulla via del mio istinto come programmatore per prevedere situazioni imprevedibili. In questo caso - non ce ne sono. Tutti capiranno sempre il mio codice che sarà sempre al massimo livello e mantenuto da me.

I commenti sono cruciali. I commenti sono orribili Non dovresti MAI usarli. usa ZEN.

Ero un programmatore in passato. Oggi I am the Boss. Questo mi ha dato two una prospettiva molto diversa sull'argomento.

Come programmatore , non capisci davvero perché hai sempre bisogno di commentare. sembra una perdita di tempo. Voglio dire, conosco il mio codice, giusto? Bene - non sempre. Prova a tornare ad un codice oscuro che tu stesso hai scritto 15 anni fa in una lingua che forse non usi così frequentemente come hai fatto tu - e improvvisamente desideri che commentassi meglio ... Oggi, dopo molti anni, commento ogni funzione ancor prima di scrivere la funzione stessa.

(piccolo modifica : dai un'occhiata a questa risposta ho appena trovato) . In qualità di capo (o proprietario di una società) - il commento è un di alto livello non un requisito, per il semplice motivo che oggi, lo staff e gli impiegati hanno poco , se non nessuno, fedeltà al posto di lavoro. possono lasciare il lavoro con un preavviso di un giorno (o senza preavviso), o semplicemente essere licenziati per una qualsiasi ragione, o in casi più estremi, potrebbe accadere qualcosa di brutto (incidente, malattia improvvisa, persino la morte - la sua parte di vita) e poi qualcun altro (chiamato code maintainer ) deve riempire le scarpe di quella persona, cioè leggere tutto il codice passato e tutti lo comprenderanno SEMPRE. Quindi commentare il solo rescue at hand NOISE.

Se stai cercando uno standard definito dal mondo per i commenti, probabilmente non lo troverai (anche se ci sono specifici della lingua (come PHPdoc ) e anche standard specifici del progetto). Perché onestamente, si pensava che non dovrebbe esistere.

Se stai cercando una risposta se commentare o meno - io dico Defiantly no !. Commenta tanto quanto il rumore che puoi ottenere.

Se stai cercando una risposta su what o where su un commento - dovrai. usa il buon senso e trova te stesso. Basta smettere di commentare - costruendo così un po ' di standard personale per il tuo lavoro futuro. (questo è quello che alla fine ho fatto).

.. e se cerchi una risposta per la tua domanda diretta "tutto o niente" - di IMHO tutto è meglio di niente Niente è sempre meglio, ma ancora - buon senso opzione non commentante è il tuo migliore amico.

    
risposta data 19.09.2015 - 09:09
fonte

Leggi altre domande sui tag