La mia domanda è semplice, come dovrei commentare durante lo sviluppo in modo che possa essere utile nei seguenti casi:
Qualsiasi esempio del mondo reale sarà molto apprezzato.
PS: Non sto discutendo se scrivere o meno commenti.
In generale, dovresti non commentare. Invece, dovresti cercare di scrivere un codice semplice, diretto, coerente e leggibile. I commenti invariabilmente non sono aggiornati. Se il tuo codice è buono, sono al massimo una duplicazione degli sforzi e nel peggiore dei casi aggiungono rumore al segnale.
Ma non è sempre possibile, dato che siamo umani e succede qualcosa. Nei casi in cui fai del tuo meglio, ma c'è una buona ragione per cui il codice non può essere semplice, diretto o coerente, quindi aggiungi un breve commento che spieghi perché non lo è.
"Fare le cose in questo modo, a causa di una potenziale condizione di competizione tra X e Y".
"Impossibile farlo in modo normale a causa delle limitazioni della libreria XYZ."
"Questo codice era brutto quando sono arrivato qui, lasciando come è per ora."
Spesso conservo la documentazione aggiornata scritta con i commenti Doxygen (o Doxygen-like). Quindi, ogni metodo / funzione ha una / due frasi che descrivono ciò che fa.
E quando una / due frasi non bastano, allora IMHO dovresti rifattarla e dividerla in parti più piccole (vedi filosofia Unix ).
Inoltre, tutti gli algoritmi "complessi" dovrebbero essere rappresentati con grafici, immagini e pseudo-codice facilmente leggibile nella documentazione aggiuntiva.
La risposta di Telastyn è abbastanza buona. Aggiungo che i commenti sono molto utili quando devi spiegare qualcosa che letteralmente non può essere espresso in una sintassi valida e leggibile. In altre parole, a volte hai solo bisogno di un diagramma o di un'immagine.
L'arte ASCII potrebbe non essere la migliore, ma può essere migliore di niente e praticamente garantita per essere visibile se l'origine è visibile (tenendo conto sia della disponibilità che del rendering). Tieni presente che includere un link a più approfondimenti (e diagrammi / immagini migliori) può essere una buona idea, ma tieni presente la possibilità che le risorse esterne non siano disponibili o non siano facilmente visualizzate.
Shamus Young ha un articolo sui commenti , che inizia con un commento effettivo lungo quasi cinquanta righe uno dei suoi progetti. Parte di quel commento ha un diagramma usato per dimostrare una griglia esagonale costruita da una griglia quadrata:
[...snip...]
+--|--+--|--+--|--+--|--+
| | | |
| . | . | . |
/ \ / \ / \ / \
/ \ / \ / \ / \
| . | . | . | . |
| | | | |
+--+--+--+--+--+--+--+--+
| | | |
| . | . | . |
/ \ / \ / \ / \
/ \ / \ / \ / \
| . | . | . | . |
| | | | |
+--+--+--+--+--+--+--+--+
^
|
+---This column gets shifted down.
[...snip...]
Prova ad esprimerlo chiaramente nei nomi di variabili e funzioni.
Ci sono quattro classi di commenti: -
Per gli articoli 1 e 4 questi dovrebbero essere in "stanze" separate nella parte superiore del codice.
Gli articoli 2 e 3 dovrebbero vivere con la linea di codice che stanno documentando.
Se hai molti commenti di tipo 2 e 3, potrebbe essere il momento di esaminare i tuoi standard di denominazione e lo stile di codifica, poiché il codice chiaro è molto più facile da capire rispetto agli spaghetti dell'alfabeto e ai commenti.
Leggi altre domande sui tag comments source-code