Quale sarebbe un buon modo per richiedere commenti?

Innanzitutto, il codice dovrebbe essere auto-documentante. Ogni riga di codice dovrebbe essere facile da decifrare e la somma totale di quelle righe di codice dovrebbe essere facilmente rintracciabile. Questo in genere significa che i metodi e le variabili dovrebbero avere nomi descrittivi ma concisi, che le operazioni dovrebbero essere chiaramente definite, schemi di progettazione che incoraggiano metodi più piccoli, uso singolo e "hack", compreso il codice che si basa su dettagli arcani dell'implementazione dietro il specifiche linguistiche, dovrebbero essere evitate. Considerate queste cose, qualsiasi coder con esperienza ragionevole dovrebbe essere in grado di decifrare il codice senza bisogno di commenti.

Detto questo, non sarai sempre in grado di farlo. Tempo, risorse, abilità tecniche, ecc. A un certo punto ti costringono a fare qualcosa in modo poco chiaro o sfacciato. Per mitigare l'oscurità del tuo codice, i commenti che indicano ciò che stai facendo e perché a volte può essere necessario. Può essere difficile per un programmatore andare fuori piano, a testa in giù a un algoritmo per rendersi conto di quando potrebbe essere necessario, quindi una fase di revisione del codice è una buona idea. Chiedi a un altro sviluppatore di leggere il codice e, se indicano qualcosa e chiedono "perché", questo è un buon candidato per alcuni commenti.

Un'altra cosa che spesso trovo utile è lo sviluppo basato sui commenti. Quando si crea un nuovo metodo, scrivere linee di commenti che descrivono in dettaglio come il metodo dovrebbe progredire attraverso l'attività progettata. Fondamentalmente stai prendendo appunti su cosa dovrebbe fare il metodo, anche se a questo punto della tua codifica non scriverete effettivamente alcun codice in quel metodo. Questo può essere inestimabile nella programmazione collaborativa, in cui un algoritmo per qualcosa di critico o estremamente coinvolto è stato progettato su una lavagna dal team e quindi dato a uno o due codificatori da implementare. Quindi, mentre si codifica, i commenti descrivono l'attività eseguita in ogni fase. Possono essere rimossi se l'operazione è chiaramente ovvia, oppure possono rimanere se la logica è più complessa dell'idea concettuale di quel codice. Tuttavia, quando usi questa tecnica, è importante capire che ciò che pensavi di fare non è sempre quello che hai finito; devi identificare quei casi e aggiornare o riscrivere i commenti.

La mancanza di commenti IMHO non è necessariamente una cosa negativa. Il più delle volte il codice può essere scritto per essere auto-esplicativo, quindi non ha bisogno di commenti (a parte la documentazione API). Le poche eccezioni sono quando il codice è intenzionalmente difficile, ad es. implementa un algoritmo noto, contiene ottimizzazioni delle prestazioni ecc.

Nel complesso, la quantità (e persino la qualità e la correttezza) dei commenti è un cattivo indicatore della qualità generale del codice. Dovresti piuttosto concentrarti sull'intera immagine: creare (e mantenere) il codice pulito, leggibile e gestibile - di cui i commenti sono solo una piccola parte.

Quindi, se vedi un pezzo di codice che ritieni abbia bisogno di commenti, considera prima il refactoring . Molto spesso il codice può essere rifattorizzato per essere facile da leggere e questo elimina la necessità di commenti.

es. se vedi un lungo metodo che esegue una lunga operazione che ha chiaramente diverse fasi / fasi distinte, potresti ritenere necessario aggiungere commenti prima di ogni fase, come

void SomeLongCalculation(...) {
  // Calculate the foo coefficient
  ...

  // Determine the bar factor
  ...

  // Sum up the blorg values
  ...

  // Calculate the yearly average
  ...

}

mentre potresti estrarre ogni passaggio in un metodo separato con un nome descrittivo:

void SomeLongCalculation(...) {
  CalculateFooCoefficient(...);
  DetermineBarFactor(...);
  SumBlorgValues(...);
  CalculateYearlyAverage(...);
}

Questo rende esplicito ogni passaggio, mantiene tutto il codice nel tuo metodo sullo stesso livello di astrazione, rendendolo così pulito e facile da leggere. Inoltre, ti consente di testare separatamente ogni sottofase.

Can you think of alternatives for this process?

Sì, posso. Quando esaminerai un pezzo di codice, fallo in coppia - un revisore e lo sviluppatore che lo ha scritto, seduto direttamente davanti allo stesso schermo. Invece di aggiungere "richiesta di commenti", lascia che lo sviluppatore principale spieghi cosa fa il codice (e perché !), E il revisore aggiunge direttamente un commento con le parole che comprende.