Devo duplicare i commenti in ogni file?

Se ti capisco bene, stai lavorando con un framework che raccomanda molti file molto simili, non ripetendo la logica, solo la struttura - codice di interfaccia che si adatta alle tue classi nel framework.

In questo caso, prendi uno dei file più rappresentativi e commentalo in modo dettagliato. Quindi, in ogni file simile, fai una breve sinossi:

  /* generic Controller for screen X. See @filename for general structure */

Se il file presenta differenze significative, menzionale nell'intestazione, quindi commentale vicino al pezzo eccezionale.

  /* special Controller for screen X. See @filename for general structure */
  /* exceptional behavior: function Y adds an event listener Z, in order to
   * handle the special behavior in case widget W receives new data. */

Hai preso in considerazione la possibilità di correggere il codice in modo che tutti questi luoghi quasi simili chiamino una routine comune e poi inseriscano il commento desiderato?

Il commento eccessivo non è molto utile che ho trovato. Se hai nomi di variabili significativi e ti concentri sulla scrittura di codice logico pulito, non dovresti aver bisogno di commentare molto pesantemente. Altrimenti ascolta Thorbjørn Ravn Andersen - il suo punto è esatto. Non ripeterti, rifatta il tuo codice per eliminare la duplicazione.

È favorevole commentare ogni file, ma se ne hai centinaia, sarebbe più facile aggiungere commenti all'inizio del file descrivendo brevemente cosa è destinato.

Se disponi di molti file simili, ti suggerisco di automatizzare il processo creando un piccolo script.

Non commentare. Se si modifica il codice, è necessario ri-commentare, è controproducente. Utilizza invece la denominazione autoesplicativa, vedi esempio.

atteggiamento dei commenti , i commenti sono quasi intuitivi

// ordinates of perpendicular triangle
var a,b;

// read ordinates
function input() {
  read(a);
  read(b);
}

// area of perpendicular triangle
function calculate() {
  return a*b/2;
}

atteggiamento di denominazione , i commenti sono inutili, il tutto è auto-esplicativo

var ordinateA, ordinateB;

function readOrdinates() {
  read(ordinateA);
  read(ordinateB);
}

function perpendicularTriangleArea() {
  return a*b/2;
}

E non confondere manuale utente con commenti nel codice !

So che questo non risponde direttamente alla domanda come posta, ma se si tratta di "cambiare le cose qui per cambiare il funzionamento del software, e questo è il significato di ogni variabile" seguita da "non modificare nulla dopo questo punto o spezzerai le cose "(come indica il tuo esempio), probabilmente stai meglio separando le parti di configurazione in un singolo file, che può essere commentato e descritto per quanto ne hai bisogno e che è incluso in tutti gli altri file .

Oltre a questo, anch'io sono d'accordo con Thorbjørn Ravn Andersen .

Hai due scelte:

• commenta il codice in un posto e nell'altro luogo usa gli stessi nomi di variabili / parametri e inserisci semplicemente un riferimento: "Vedi i commenti alla routine Foo".
• fornire un documento separato e inserire riferimenti ad esso (ad esempio "Vedere la sezione 4.3").

Codice e commenti sono due flussi separati di informazioni e tenerli sincronizzati è sempre un po 'di dolore. Soffriamo di questo dolore a causa dei vantaggi di avere informazioni sul contesto del codice / il contratto del codice / etc, ma è ancora un dolore. Come altri hanno già detto, la scrittura di codice leggibile pulito elimina la necessità di parte di commenti. Quindi è una soluzione parziale a un problema che in realtà non è completo.

Se il tuo cliente desidera quel livello di commento e sei contrattualmente obbligato a fornirlo, ovviamente dovrai svolgere il lavoro, ma direi che questa è una spesa non una investimento per te.

Tuttavia, a seconda di come hai sviluppato il software in primo luogo, potrebbe esserci una scorciatoia, permettendoti di aggiungere i commenti con meno sforzo di quanto potresti pensare:

• Se utilizzi un sistema di controllo della versione come mercurial che tiene traccia delle copie, e lo hai usato per creare i tuoi file duplicate code , potresti essere in grado di utilizzare le strutture in il tuo VCS per fare un po 'di questo lavoro per te.

Ad esempio, se hai creato i file di codice duplicato copiando un file antenato comune usando il comando copia di VCS e poi modificando il file copiato, potresti essere in grado di aggiornare alla versione in cui il comune il file dell'antenato è stato modificato l'ultima volta, aggiungere i commenti lì e quindi unire tali modifiche nella versione corrente. Con mercurial almeno, le modifiche al file antenato comune devono essere replicate attraverso ciascuna delle copie di quel file.

Ho usato questa tecnica più volte, solitamente dividendo un file contenente più classi in più file con una classe ciascuno. Sono rimasto molto colpito dal fatto che mercurial sia stato in grado di unire in correzioni di bug pre-split e applicarle correttamente a ciascuno dei file sorgente post-split senza l'intervento manuale.

• Se non hai tracciato copie del genere, crea file patch e applicali a ciascuno dei tuoi file sorgente.

Il meccanismo di patch ha alcuni 'give' . Se modifichi uno dei tuoi file sorgente per aggiungere i commenti e poi prendi un diff per la versione nel controllo di revisione, ti ritroverai con un file patch. Questo può essere applicato in modo abbastanza pulito a molti dei tuoi altri file sorgente.

Entrambe queste opzioni potrebbero ridurre notevolmente il lavoro richiesto.