Cosa devo inserire nei commenti durante il commit del controllo del codice sorgente?

8

Sono uno sviluppatore solitario e gestisco un server SVN per il controllo del codice sorgente. Finora, non ho seguito nulla di specifico mentre ho commesso i miei cambiamenti.

Stavo solo rivedendo i miei precedenti commit e non riuscivo a dare un senso ai miei commenti.

Che cosa inserisci nei commenti durante l'accettazione dei tuoi assegni?

    
posta Devdatta Tengshe 01.12.2011 - 09:22
fonte

11 risposte

11

Potresti essere interessato a leggere questo: link .

Se non stai usando un bug tracker e, in quanto tale, non puoi includere un id / numero di segnalazione bug, devi essere molto descrittivo nei tuoi commenti. Altrimenti, se scrivi semplicemente "problema fisso con X", ad esempio, due settimane dopo il commit non ricorderai quale fosse il problema. In tal caso, dovrai confrontare le versioni di commit prima e dopo per capire di cosa si tratta.

Quando ho iniziato a sviluppare applicazioni professionalmente, non abbiamo utilizzato un bug tracker e ricordo che a volte i commenti erano molto descrittivi (anche troppo), a volte non c'era alcun commento, era un disastro. Con un id inseguitore di bug, i commenti sono molto più utili e con poche altre parole potresti persino indicare perché hai apportato quella particolare modifica. Inoltre, IDE come Eclipse, ad esempio, ha plugin che rilevano l'id del tracker bug nei commenti (e anche nel codice sorgente) e possono fornire un link cliccabile alla pagina web del bug tracker.

    
risposta data 01.12.2011 - 09:36
fonte
7

Che cosa ti aspettavi di trovare nei commenti dei tuoi precedenti commit?

Inserisci le informazioni nei tuoi prossimi commit.

A volte basta un ID ticket, un ticket che rappresenta una segnalazione di bug o una richiesta di funzionalità.

    
risposta data 01.12.2011 - 09:39
fonte
4

I commenti sul commit riguardano il vedere facilmente ciò che è stato cambiato. Sono lì per il vostro riferimento, quindi quanti dettagli ci mettete dipenderanno da quanto impegno volete spendere adesso per farvi risparmiare tempo in futuro. In generale, un piccolo sforzo nel tempo di commit ha il potenziale per risparmiare molto tempo in futuro.

Ad esempio, supponiamo di aver modificato <= in > e ++ in -- in un ciclo, ma non aggiungere un commento di commit descrittivo. In seguito, sarebbe difficile trovare la revisione in cui è stata invertita la direzione dell'iterazione. Se avessi commentato " Direzione inversa di blah index traversal ", sarebbe molto più facile trovare tale revisione cercando nel log di revisione.

Questo è il motivo per cui includere le informazioni di tracciamento nei messaggi di commit è davvero una buona idea. Supponiamo che tu risolvi un bug, quindi in seguito il problema viene riaperto perché non è stato risolto completamente. Se il tuo commento di commit della correzione originale menzionava l'identificatore del tracker del problema, puoi facilmente trovarlo e in seguito puoi facilmente trovare tutte le revisioni associate a quel problema.

    
risposta data 01.12.2011 - 12:38
fonte
2

Tendo a scrivere una forma concisa di ciò che sto commettendo; se è per un'attività specifica, includerò il numero di attività nel messaggio. Cose come:

Changed foobar module to account for the new baz; created quux pages and data objects.

Che cosa non fare è scrivere qualche assurdità come "Oops" o "Commenti aggiunti" (entrambi i quali ho visto aggiunti nei registri di commit da un collega), o peggio di tutti fare qualcosa come ho visto l'altro giorno - Un singolo file è stato archiviato, con il messaggio di commit "Commento" (citazione esatta). Cosa è stato aggiunto, potresti chiedere? Qualcosa con l'effetto di:

if (z == true) { 
    x = y; // x is being overridden here... <--- added in commit
}

E no, non siamo misurati dal numero di commit.

    
risposta data 01.12.2011 - 22:35
fonte
1

Penso che tutto questo si riduce a come gestisci i tuoi progetti. Per quanto mi riguarda, tendo a impegnarmi ogni volta che finisco una funzione che voglio spingere ad una build di rilascio. Dato che nel mio caso, ogni funzione risulta in un commit, io uso la storia e il numero di rilascio della mia funzione come mio commento. Lo stesso vale per correggere i bug. Comincio con uno spike, ricavo una storia, uso la storia per descrivere i cambiamenti che ho bisogno di fare, e ancora una volta mi impegno a controllare il codice sorgente con una storia nei commenti.

    
risposta data 01.12.2011 - 09:38
fonte
1

Numero ID.

La maggior parte dei tracker di problemi ha un formato in cui è possibile analizzare gli ID di problema al di fuori dei messaggi di commit e il gruppo esegue commit con problemi.

Se non usi un tracker di problemi, dovresti, non importa che tu sia uno sviluppatore solista, ho approfondito l'argomento su un'altra risposta :

Use an issue tracker. It doesn't matter you are a lone wolf, keep track of everything you do for your project, whether it's a feature or a bug. Make a feature / components list. Mark truly essential components as version 1.0 and all else as version 2.0. And then delete everything that's marked as 2.0.

Ok, poiché la domanda ha ricevuto una notifica di mod per risposte più lunghe, mi sento obbligato ad espandere:

Sì, ho appena inserito l'ID del problema nei commenti di commit, nient'altro. È allora che nei progetti solisti, nei progetti di gruppo è tutta un'altra storia. Non sto proponendo di mettere solo l'ID del problema, ci dovrebbe essere qualcosa di più lì, ma:

  1. Nei progetti da solista è estremamente allettante non documentare nulla,
  2. L'impostazione dell'ID problema indica per impostazione predefinita che hai completato la procedura di configurazione di un tracker dei problemi,
  3. Questo è abbastanza buono per me.

Utilizzare in modo efficace un tracker di problemi durante lo sviluppo di solo è un risultato molto più grande rispetto ai commenti di commit. Sarebbe bello se avessi la motivazione di aggiungere qualcosa di utile nei commenti, ma non lo faccio.

    
risposta data 01.12.2011 - 09:39
fonte
1

In genere pongo lo scopo del check-in in alto. Questo potrebbe essere il nome di una richiesta di funzione, numero di biglietto, ecc.

Quindi lo seguo con l'elenco dei file interessati e le modifiche specifiche richieste in ogni file. Ciò è particolarmente utile quando si guarda la cronologia delle revisioni di un file rispetto al progetto / cartella.

Qualcosa di simile

Ticket 101 fix web service exception when uploading widget

Bug was caused by users uploading incomplete widgets (widgets without wonkers)

webservice.cs:  
  improved post validation for incomplete widgets
  added default exception handler to ProcessWidget
widget.cs:  handled the SqlException when inserting widgets without wonkers
    
risposta data 02.12.2011 - 06:12
fonte
0

In generale, ciò su cui hai lavorato in quel commit è un buon inizio:)

(per curiosità ... cosa hai scritto se non riuscivi a capirci qualcosa?)

    
risposta data 01.12.2011 - 09:36
fonte
0

Le modifiche che hai apportato al codice e qualsiasi altra cosa che potrebbe essere rilevante tra cui mettere non limitato a correzioni di bug, nuove funzionalità, interruzioni di funzionalità, cambiamenti nelle librerie, ecc. Naturalmente dal momento che il codice è impegnato in piccoli incrementi non avrà tutto quanto sopra. Per esempio. se stai correggendo un bug potresti fare più modifiche. Ci saranno più commit per correggere il bug, ma quali modifiche hai apportato per risolvere il bug in particolare.

    
risposta data 01.12.2011 - 09:36
fonte
0

Il bit più importante di informazioni nel log di commit è il 'why', non il 'what'.

Un breve riassunto delle modifiche può essere utile, ma in genere è possibile ottenere tali informazioni dal diff stesso. Non è un problema enorme se manca.

Guardando indietro a un registro di commit, vorrai sapere perché è stata fatta questa modifica. Un bug ID può fare molto per rispondere a questa domanda. A volte sono necessarie ulteriori spiegazioni. Ad esempio, se si aggiusta un probem su input errati, spiegare quale input ha causato il problema e se non è banale anche come potrebbe verificarsi.

    
risposta data 01.12.2011 - 14:29
fonte
0

Stiamo usando assembla sul nostro progetto. Costruiamo il cardwall con tutti i featuers / bug che devono essere eseguiti e quando ci accingiamo ci limitiamo a fare riferimento a questo ticket

Ad esempio:

see #243
 - Grid listed all users with an income more then 1000$ but not the ones that have
   exactly 1000. Added a >= in the file xy.cs on the line xyz

In questo modo siamo in grado di individuare le modifiche più rapidamente e trovare alcuni errori più facili

    
risposta data 01.12.2011 - 14:51
fonte

Leggi altre domande sui tag