Come fare riferimento a specifiche aree di codice nella documentazione?

Sto per lasciare un progetto e prima di andare il mio capo mi ha chiesto di documentare il codice (non ho documentato molto bene). Non è un grosso problema, il progetto non è terribilmente complesso. Ma sto trovando posti nella mia documentazione in cui vorrei dire: "Avviso sulla linea XYZ che questo e ciò accade."

In questo caso, non ha senso fare riferimento a un numero di riga specifico, poiché l'aggiunta o l'eliminazione di una singola riga di codice supererebbe immediatamente la documentazione. Esistono alcune best practice per fare riferimento a una specifica riga di codice senza fare riferimento ad essa per numero di riga?

Ho considerato di sporcare il codice con commenti come:

/* linetag 38FECD4F */

Dove "38FECD4F" è un tag univoco per quella riga specifica. Quindi posso inserire la documentazione "Sulla riga taggata '38FECD4F', notare che questo e ciò accade."

Altre idee? Sento che è generalmente meglio documentare le unità di codice nel loro insieme, piuttosto che parti specifiche di esse, ma nel caso di questo particolare progetto ci sono LUNGHE fasce di codice procedurale, che non sono mai state rifattate in unità più piccole.

Se ho capito bene, sembra che tu abbia un problema unico. Quello che vuoi fare si riferisce a una specifica riga di codice nei commenti che sono scritti in qualche altra parte dello stesso codice.

Di solito non mi imbatto in tali scenari in cui ho bisogno di fare riferimento a una riga esatta in alcuni commenti scritti altrove - in genere il codice è documentato proprio dove è scritto.

Non conosco alcun modo standard per farlo - ma dalla cima della mia testa ...

Puoi fare riferimento a parti di codice tramite il suo contesto, ovvero le cose che li circondano.

Si noti sopra la definizione di func1 () che tale e ciò accade

Si noti che subito dopo il ciclo for che scorre su recordXYZItr, stiamo anche chiamando il metodo gc ()

Attenzione: nel metodo yahoo (), subito dopo la dichiarazione della variabile PQ, stiamo anche scambiando i valori in A e B, quindi anche l'oggetto mapABC deve essere copiato

Un altro modo è quello di aggiungere tag descrittivi. Invece di qualcosa del genere 38FECD4F, puoi dire Some XYZ implementationo BUGFIX 1474, quindi fare riferimento a quello da qualche altra parte.

Dipende molto da come è stato scritto il codice e capisco che potrebbe indurre un sacco di refactoring che non sei qui per fare.

Ma ... se hai bisogno di fare riferimento a una specifica riga di codice come intera unità, non significherebbe che è un codice che rappresenta un'operazione astratta, e quindi potrebbe essere refactored nel suo metodo / funzione? Una volta che è in un metodo, è abbastanza facile, basta fare riferimento a namespace.class.methodNaturalmente ciò significa avere metodi che sono molto piccoli, lunghi circa 5-10 righe o anche meno. Con Doxygen, puoi mettere la documentazione in cima al metodo e rimarrebbe sempre sincronizzata con il nome del metodo / classe / spazio dei nomi.

Ti suggerisco di adottare un approccio diverso, oltre al collegamento da una documentazione esterna al codice:

1. aggiungi commenti al tuo codice, usando uno strumento come doxygen .

2. nel caso in cui sia necessario spiegare alcuni concetti in modo più dettagliato di quanto sia appropriato nella documentazione del codice (appena creato), è sempre possibile creare un documento separato e collegarlo a quello.

In questo modo è possibile generare facilmente la documentazione come pagina Web o PDF e rimanere coerente con il codice. L'uso di alcuni tag artificiali diventerà molto difficile da mantenere e ancora più difficile da capire per i non iniziati.