Convenzioni di commento

Question

Desidero sapere quali sono alcune linee guida per i commenti? Sto codificando in Java per la lezione. Voglio avere un codice leggibile. In un'altra domanda mi è stato detto "come" i commenti dovrebbero essere riservati per sezioni di codice difficili. Mi è stato detto che i miei commenti sul codice non hanno aggiunto informazioni. I commenti non sono solo per i lettori. Sono anche dei promemoria per l'autore del loro intento originale e per aiutare ad abbinare i simboli di raggruppamento.

Sono nuovo in Java e StackOverflow. Perché mi sto prendendo in giro? Pensavo che questo sito web fosse stato progettato per consentire ai programmatori di aiutarsi a vicenda. Mi sento un bersaglio perché ho una domanda con un voto di -3. Siamo qui per aiutare i nuovi programmatori o qui a gonfiare il petto con orgoglio per gli altri?

Answer 1

Diverse persone hanno stili diversi, quindi in qualche modo qualsiasi cosa tu abbia letto qui saranno solo i suggerimenti di qualcuno. Non ci sono regole fredde e rigide per commentare.

La cosa più importante da sapere sui commenti in Java è Javadocing. È un tipo speciale di commento che può essere analizzato e utilizzato negli IDE (come Eclipse e Netbeans), per facilitare il processo di codifica. I commenti Javadoc iniziano con a/** e terminano con un */È proprio come un normale commento su più righe ma con due asterischi nel primo.

I commenti Javadoc vengono inseriti all'inizio di classi, metodi o variabili di istanza per descrivere ciò che fanno. Esistono metodi standard per formattare i dati nel commento, che sono tag. Alcuni tag comuni sono @author e @version. Puoi vedere alcuni dei suggerimenti di Sun per scrivere commenti Javadoc qui: http://java.sun.com/j2se/javadoc/writingdoccomments/

Quello che mi piace fare dopo è usare commenti a riga singola (la doppia barra //) per descrivere la mia logica. Se ho bisogno di più di una linea, userò solo più commenti a riga singola. Il vantaggio di questa tecnica è che se è necessario commentare in seguito ampie porzioni di testo, è possibile utilizzare il normale commento su più righe/* */senza preoccuparsi del problema dei commenti nidificati.

Spero che questo ti aiuti a farti un'idea approssimativa su come utilizzare i commenti in java. Il mio consiglio è in parte un prodotto del lavoro di assistente didattico che ho per la classe Intro Java di un'università e in parte per il lavoro nel settore. Altri con uno sfondo diverso potrebbero avere più suggerimenti.

Answer 2

mi piacerebbe seguire le linee guida Stack Overflow menzionati nei seguenti posti:

• When Not to Comment Code
• Function/Class Comment formatting Conventions
• What is your personal approach/take on Commenting?

Answer 3

Se si torna al codice in due settimane e non puoi facilmente capire cosa hai fatto, richiede più commenti o refactoring per rendere il codice più chiaro.

Detto questo, le linee guida per i commenti dovrebbero provenire dalle politiche sul posto di lavoro o, nel tuo caso, dal tuo insegnante. Se il tuo insegnante sta dicendo che non hai bisogno di commenti in un certo posto, allora non lo fai.

Quando hai finito con la lezione, sentiti libero di commentare come vuoi.

Answer 4

I commenti sono per il lettore del codice. Naturalmente, il lettore del codice potrebbe anche essere lo scrittore. Ma in entrambi i casi, vuoi dire al lettore cose che non possono facilmente vedere dal codice. I commenti eccessivi o ridondanti tendono a sfuggire al codice reale.

Answer 5

Le grandi cose che commentano:

• Il nome di un algoritmo. Ad esempio, se sto scrivendo un algoritmo per calcolare i pixel in una linea tra due punti, lascerei un commento dicendo che si tratta di un'implementazione dell'algoritmo di Bresenham.

• Se invii un valore codificato, magico, ad una funzione (ad esempio, true, null, 42, ecc.), Commenterei ciò che rappresenta questo valore.

• Se si implementa una struttura dati, mi piace commentare dicendo quali operazioni è progettata per ottimizzare. Ad esempio, se stavo implementando una coda (dovresti usare un framework per una coda), direi qualcosa come la struttura dei dati FIFO con O (1) insert, remove e size.

• Cerco di lasciare un commento in cima a ogni classe e metodo il cui nome non rivela tutte le complessità dell'implementazione. Tuttavia, sono spesso riluttante a farlo. Più spesso che no, di fronte a questo problema un refactoring è più appropriato.

Answer 6

Prima di tutto con codice leggibile e commenti leggibili sono due cose completamente diverse. Codice leggibile è il codice utilizza buona variabile, metodo, nomi di classe, ecc.

I commenti leggibili sono più una questione di gusto personale. Ad alcune persone piacciono i commenti per seguire le regole grammaticali che verrebbero usate per scrivere un libro mentre altri non potrebbero importare di meno delle cose grammaticali.