Commenti privati in git

Per rispondere direttamente alla tua domanda:

Se si presta attenzione a utilizzare sempre commit separati per aggiungere commenti, è possibile rimuovere successivamente questi commit (utilizzando git rebase -i ). Finché i commenti e le altre modifiche al codice non toccano le stesse linee (o linee molto vicine tra loro), il rebase non dovrebbe produrre alcun conflitto.

Tuttavia, sono d'accordo con Doc Brown sul fatto che dovresti provare a scrivere commenti che possano rimanere e aiutare gli altri. Naturalmente, fare un passaggio finale con rebase è probabilmente ancora una buona idea, per migliorare / correggere i commenti (dato che i tuoi primi commenti potrebbero essere stati errati).

Inoltre, anziché utilizzare i commenti, potresti voler cambiare i nomi di variabili e funzioni: spesso è un modo migliore per migliorare la leggibilità. Ma questa è un'altra domanda ...

Quindi è necessario aggiungere molti commenti per rendere il codice leggibile e comprensibile, il che è spesso un segnale, diciamo, di una qualità mediocre del codice. Cosa ti fa credere che anche gli altri membri del team non traggano beneficio da questi commenti? O che non ne avrai più bisogno dopo, quando dovrai guardare di nuovo lo stesso codice? Impara a scrivere quei commenti in un modo in cui non devi rimuoverli in seguito.

O ancora meglio, invece di scrivere molti commenti, impara a rifattorizzare il codice in un modo che diventa più auto-documentante, quindi molti commenti possono essere omessi.

Se pensi davvero di non poter cambiare la tua abitudine a lavorare in quel modo, ti suggerisco di lasciare i tuoi commenti aggiungendo ed eliminando nella cronologia. In una buona squadra, non ci dovrebbero essere motivi per nascondere il modo in cui lavori dal resto della squadra.

Sono d'accordo che git rebase -i sia il modo corretto per rimuovere le modifiche locali prima di spingere.

Sono anche d'accordo che se senti la necessità di aggiungere commenti per rendere comprensibile il codice, è probabile che aiutino anche i tuoi colleghi e quindi dovresti spingerli.

In entrambi i casi i commenti dovrebbero essere aggiunti in un commit separato in cui non si modifica nient'altro che i commenti. Se aggiungi un po 'di commenti alla volta, puoi considerare di combinare i commenti commessi utilizzando fixup comando in git rebase -i per inserire meno pezzi.

Se metti i commenti su linee separate, la colpa attribuirà solo le linee di commento ma non le linee di codice, poiché non sono cambiate. Generalmente il codice non deve essere troppo ampio, quindi si adatta allo schermo con toolbox IDE su entrambi i lati, quindi lo spazio raramente disponibile alla fine della riga è comunque molto utile.

Anche se tocchi le linee e la colpa inizierà ad attribuirle, di solito ci sono molti cambiamenti in una linea e quando si guarda un'annotazione della colpa, è raro che si cerchi l'ultima modifica. Non ci sono scuse per non vedere quale sia stata l'ultima modifica alla linea e non per rimproverare la colpa della revisione precedente.

Questo è uno dei motivi per cui l'opzione preferita da utilizzare quando si cerca un codice è "pickaxe", git log -S testo (e git log -G modello ). Se dai solo il codice sulla linea, non troveranno il commit che ha aggiunto un commento, solo il commit che ha effettivamente introdotto il codice.

E ricorda, rendere il codice più facile da capire, almeno rinominando le cose per essere più descrittive, è meglio dei commenti, perché i commenti potrebbero diventare obsoleti mentre il codice è refactored, ma il codice stesso non può.

Ho ancora una raccomandazione, anche se è solo parzialmente pertinente.

Metti la spiegazione del codice nel registro di commit!

Quando apporti una modifica, in particolare a un codice che non capisci molto bene o a un codice non banale o non ovvio, è utile scaricare tutti i tuoi pensieri quando apporti la modifica nel messaggio di commit .

Includi ciò che hai scoperto su come funziona il codice, un'analisi dettagliata del perché è stato sbagliato e la spiegazione di come il cambiamento dovrebbe risolvere il problema.

A differenza dei commenti nel codice che spesso diventano obsoleti, i commenti nel log di commit sono associati a uno stato particolare del codice e possono essere selezionati in modo selettivo da blame o "pickaxe" ( log -S / log -G ).

Quindi la prossima volta che devi modificare del codice, eseguirai blame e log su di esso e leggerai i commenti e dovresti trovare tutte le spiegazioni su come il codice si è evoluto con chiara indicazione di quali obsoleti quali. E tutto ciò senza ingombrare il codice.

Ovviamente i commenti dovrebbero continuare a spiegare principalmente perché e cosa in termini di alto livello , mentre i termini di basso livello di cosa e il come dovrebbe essere ovvio dal codice e se non lo è, pulire il codice è molto meglio quindi commentarlo.