Lo stile di commento influisce sul modo in cui i lettori interpretano il codice?

8

Questa domanda mi ha ossessionato negli ultimi 2 mesi.

Qualche tempo fa un amico che è un grande programmatore mi ha dato alcuni codici di esempio, e per la prima volta ho notato uno stile unico di organizzazione dei commenti. Si è sforzato di progettare i commenti in un modo che mi rendesse più comodo con il codice stesso. Ad esempio:

/////////////////////////////////////////////                                                   //                                             //
//  This code prints a basic "Hello world" //
// message to the console screen. You can  //
// change the text in the brackets.        //
//                                         //
/////////////////////////////////////////////

#include <iostream>

int main() {
  cout << "Hello world";

}

quando avrebbe potuto semplicemente scrivere

/* This code prints a basic "Hello world" message to the console, change text in brackets */

 #include <iostream>

int main() {
  cout << "Hello world";

}

Questo tipo di esempio solo su una scala più grande. Trovo che questo sia un po 'improduttivo nelle situazioni professionali, ma in una situazione di apprendimento, sembra l'ideale.

La domanda qui è, se lo stile di commento influisce su come il lettore capisce il codice. Nella mia opinione personale, l'opzione n. 1 è più carina alla vista e più facile da seguire della # 2. Il modo in cui commentate il codice influisce sulla capacità di comprendere il vostro codice o è solo uno spreco di tempo e spazio?

    
posta Bugster 20.02.2012 - 20:30
fonte

8 risposte

5

Il layout di un programma da uno spazio bianco e una prospettiva di commento avrà un grande impatto sul modo in cui uno sviluppatore può leggere il tuo codice.

Prettier to the eye and more easy to follow è soggettivo e non sarà lo stesso per ogni programmatore.

Detto questo, alcuni sviluppatori preferiscono vedere più codice sullo schermo contemporaneamente, mentre altri preferiscono avere più spazi bianchi / commenti.

Alla fine della giornata, ti sarà più comodo leggere il codice che sei abituato a leggere.

Uncle Bob Martin, autore di Pulisci codice rende l'argomento che i commenti sono usati frequentemente per scusare il codice errato e dovrebbe essere evitato quando possibile Invece il tuo codice dovrebbe essere leggibile e organizzato abbastanza bene da permettere ad un altro sviluppatore di prenderlo facilmente e iniziare a lavorare.

    
risposta data 20.02.2012 - 20:37
fonte
7

Credo che la formattazione del codice possa fare un'enorme differenza nella leggibilità, ma per la maggior parte il codice ben formattato (o anche solo il rientro coerente) mi dà una sensazione calda e confusa che lo scrittore abbia effettivamente preso un po 'di attenzione, piuttosto che tagliare -n-incollando qualunque frammento avesse a portata di mano.

Non sono così sicuro dei commenti. Codice che scrivo, credo fermamente che il commento aiuti. D'altra parte, se voglio capire il codice "enterprise" che ho incontrato al lavoro, di solito cancelli tutti i commenti, riformatto il codice per avere un indentation coerente e lo stampo su carta per leggere in dettaglio, contrassegnando i blocchi di base con la matita, ecc.

Questa contraddizione (io: buoni commenti, tutti gli altri: commenti fuorvianti) mi fa pensare che i commenti siano ampiamente sopravvalutati. Anche il mio.

    
risposta data 20.02.2012 - 23:25
fonte
6

Sì, lo stile di commento influisce sulla leggibilità (come no?), ma direi che l'esempio che hai dato è uno stile molto povero. La formattazione eccessiva è proprio questa: eccessiva.

Scrivere buoni commenti è un'abilità da praticare e perfezionare, proprio come scrivere codice.

    
risposta data 20.02.2012 - 20:37
fonte
2

IMHO, il primo è adatto per commentare ciò che fa una classe o all'inizio di un file sorgente; il secondo è adatto per descrivere cosa fa il seguente blocco di codice. per i metodi, vorrei usare

//////////////////////////////////////////////////////////////////////
This code prints a basic "Hello world" message to the console screen. You can change the text in the brackets. 

Oltre ad altre grandi risposte, ritengo che la coerenza nello stile dei commenti sia un altro punto. Se utilizzi diversi tipi di stili di commento per lo stesso tipo di attività che danneggerebbe piuttosto la leggibilità del tuo codice.

    
risposta data 21.02.2012 - 09:30
fonte
1

L'esempio che date è un po 'estremo, ma sì, i commenti hanno una funzione molto importante.

Lo scrittore del codice ha un modello mentale di ciò che deve fare. I commenti servono per

  • comunica al lettore che cos'è questo modello mentale e
  • esprime la mappatura tra il modello mentale e il modo in cui il codice lo implementa.

In questo modo, se i requisiti cambiano, è più probabile che le corrispondenti modifiche al codice possano essere apportate correttamente, sia dall'autore originale sia da chiunque vi venga in seguito.

È anche utile provare a scrivere il codice in modo tale che si spieghi da solo, ma raramente ha successo al 100%, quindi i commenti sono necessari.

    
risposta data 20.02.2012 - 20:36
fonte
0

Una risposta rapida alla domanda è "Sì". I commenti e lo stile dei commenti influenzano chiaramente la leggibilità e la comprensibilità del codice. Questa è l'idea generale, ma la qualità delle descrizioni dei commenti e il loro design sono puramente soggettivi.

Hai mai provato a leggere il codice e i commenti di qualcun altro? La maggior parte dei programmatori scrive codice e commenti in base al proprio stile e livello di conoscenza. Leggere i loro commenti e il codice è come cercare di entrare nella loro mente e seguire le loro pratiche.

Un modo per evitare questo problema è utilizzare una "guida principio / stile" di base che descriva brevemente le linee guida di base per la struttura del codice, lo scopo e i commenti. Questa guida deve essere costantemente seguita dalle persone che scrivono il codice e tutti gli altri che potrebbero leggere il codice ed eventualmente estenderlo.

    
risposta data 21.02.2012 - 11:18
fonte
0

Stilisticamente, andrei con due forme di commento (per C ++ / Java)

/**
 * Multi-line comment
 */

o

// Single-line comment

un IDE con evidenziazione della sintassi è sufficiente per attirare l'attenzione sul commento, non è necessario essere fantasiosi con la formattazione.

    
risposta data 21.02.2012 - 15:20
fonte
0

Sì, lo stile di commento influisce sicuramente sulla leggibilità. Qualsiasi stile di commento che mi permetta di identificare rapidamente i commenti, così posso evitare di leggerli, aiuta moltissimo quando quello che sto cercando di fare è leggere il codice .

Ancora meglio è uno stile di commento del codice che mi consente di utilizzare l'IDE minimizzando completamente i commenti, quindi non devo spendere l'energia per leggere intorno a loro.

    
risposta data 21.02.2012 - 16:00
fonte

Leggi altre domande sui tag