Usiamo la sovversione - Dovremmo comunque inserire commenti nel mio codice? [duplicare]

Naviga le tue risposte
1

Ho sollevato in una riunione un fastidio che le modifiche al codice non sono state commentate all'interno del codice stesso. Usiamo SVN (Subversion) per il controllo del codice sorgente e mi è stato comunicato che puoi andare in SVN e controllare la cronologia e vedere le modifiche.

La mia domanda è questa è una best practice? Mi sembra più facile inserire il commento nel codice stesso con il riferimento di difetto / user story (usiamo Rally / Agile) AND nell'intestazione svn quando si verificano le modifiche. I miei capi sembrano pensare che metterlo in codice non è necessario, e ho detto loro che non ero affatto d'accordo con quella pratica. Mi è sempre stato insegnato che i commenti nel codice non sono mai male. Questo non è il mio primo concerto.

Ero ancor più sconvolto quando mi ha detto che il suo capo era stato abituato a strappare commenti in qualche codice. Dopo che ho smesso di prendere i frullati, volevo ... vomitare.

Cosa ne pensi dei commenti in codice vs / con commenti nel controllo del codice sorgente e cosa fai come best practice?

    
posta Manoj R 04.02.2014 - 15:39
fonte

2 risposte

4

Assolutamente! Servono due scopi completamente diversi.

  • I tuoi messaggi di commit descrivono solo il motivo per cui stai commettendo quel particolare changeset: la richiesta del cliente, la correzione di un particolare bug, ecc. Questi sarebbero i punti in cui registri i riferimenti della tua user story o i riferimenti ai bug:

Revised method XYZ to cover additional use case highlighted by user story ABC.

Fixing bug 1234 which was caused by an off-by-one error in main loop

  • Commenti in il tuo codice dovrebbe descrivere perché il tuo codice è scritto così com'è, o commenti descrittivi sui metodi & variabili (come le intestazioni da elaborare da JavaDoc). Vedi l'esempio fornito alla fine della risposta precedente.

I due concetti sono indipendenti. Se perdi il controllo del codice sorgente o esegui la migrazione del codice a un nuovo VCS senza conservare la cronologia, hai perso tutta la documentazione se segui ciò che suggeriscono i tuoi capi. E se stai provando a eseguire il debug di un sistema in produzione senza commenti nel codice, ti capita continuamente di leggere centinaia di commit dei registri SVN mentre cerchi di interpretare il codice & capire cosa va dove.

La prospettiva di stipare i commenti di centinaia di righe di codice (che dovrebbero essere sottolineate con il codice) in un singolo messaggio di commit è spaventosa.

    
risposta data 04.02.2014 - 15:56
fonte
7

Penso che non ci sia una risposta generale. Dipende. Il commento extra del codice potrebbe causare disturbi e renderlo meno leggibile.

Commenti nel codice come questi: 

// 2014/01/17 [email protected] changed this path:
$path="/...";

Non dovrebbe essere lì. Dovrebbero essere nel commento del controllo di versione, insieme ad altre modifiche. Inoltre, dovresti avere un sistema di ticketing in cui viene riportato questo cambiamento. Supponiamo che tu abbia un problema nel tuo sistema di ticketing numerato 12345. Poi, ogni volta che vuoi vedere cosa è stato fatto e perché, e chi ha chiesto di cambiare questo URL, ecc., Vai al tuo sistema di ticketing e cercalo. Quindi troverai il numero correlato 12345. Quindi dovresti fare il grep per la storia di subversion per il problema 12345 (buona pratica per aggiungere il numero di rilascio correlato nel tuo commento di commit), ecc.

Ma commenti come questi: 

// path must be retrieved from file_helper broker, as it crashes otherwise because...
$path=file_helper::get_path(...)

Sono molto utili e valgono la pena di essere lì per sempre.

    
risposta data 04.02.2014 - 15:47
fonte

Leggi altre domande sui tag

E 'possibile creare un'istanza di un'interfaccia (e.g-Map Interface)? Se è allora come? Come abbreviare la dichiarazione del caso da hades? [duplicare]