¿Cómo hacer referencia a áreas específicas de código en la documentación?

Estoy a punto de abandonar un proyecto, y antes de irme, mi jefe me ha pedido que documente el código (no lo he documentado muy bien). No es gran cosa, el proyecto no es terriblemente complejo. Pero estoy encontrando lugares en mi documentación donde me gustaría decir: "Observe en la línea XYZ que tal y tal cosa sucede".

En este caso, no tiene sentido referirse a un número de línea específico, ya que agregar o eliminar una sola línea de código inmediatamente desactualizaría la documentación. ¿Existe alguna práctica recomendada para referirse a una línea de código específica sin referirse a ella por número de línea?

He considerado ensuciar el código con comentarios como:

/* linetag 38FECD4F */

Donde "38FECD4F" es una etiqueta única para esa línea específica. Luego puedo poner en la documentación, "En la línea etiquetada '38FECD4F', observe que tal y tal sucede".

¿Alguna otra idea? Siento que generalmente es mejor documentar las unidades de código en su conjunto, en lugar de porciones específicas de ellas, pero en el caso de este proyecto en particular, hay LARGAS franjas de código de procedimiento, que nunca se han refactorizado en unidades más pequeñas.

Si lo entiendo bien, parece que tienes un problema único. Lo que desea hacer se refiere a una línea de código específica en los comentarios que están escritos en alguna otra parte del mismo código.

Por lo general, no me encuentro con tales escenarios en los que necesito referirme a un número de línea exento en algún comentario escrito en otro lugar; en general, el código se documenta justo donde está escrito.

No conozco ninguna forma estándar de hacer esto, pero fuera de mi cabeza ...

Puede referirse a porciones de código a través de su contexto, es decir, cosas que los rodean.

Observe arriba de la definición de func1 () que tal y tal sucede

Tenga en cuenta que justo después del ciclo for que itera sobre recordXYZItr, también estamos llamando al método gc ()

Precaución: en el método yahoo (), justo después de la declaración de la variable PQ, también estamos intercambiando los valores en A y B, por lo que el objeto mapABC allí también debe copiarse

Otra forma es agregar etiquetas descriptivas. En lugar de algo como 38FECD4F, puedes decir Some XYZ implementationo BUGFIX 1474, y luego referirte a eso en otro lugar.

Depende mucho de cómo se escribió el código, y entiendo que puede inducir un montón de refactorización que usted no está aquí para hacer.

Pero ... si necesita referirse a una línea de código específica como una unidad completa, ¿no significaría que es un código que representa una operación abstracta y, por lo tanto, podría refactorizarse en su propio método / función? Una vez que está en un método, es bastante fácil, solo refiérase a namespace.class.methodPor supuesto que significa tener métodos que son muy pequeños, de aproximadamente 5-10 líneas de largo o incluso menos. Con Doxygen, puede colocar la documentación sobre el método, y siempre se mantendrá sincronizada con el nombre del método / clase / espacio de nombres.

Le sugiero que tome un enfoque diferente, que no sea vincular desde alguna documentación externa de código a código:

1. agregue comentarios a su código, utilizando una herramienta como doxygen .

2. En caso de que sea necesario explicar algún concepto con más detalle de lo que es adecuado dentro de la documentación del código (recién creado), siempre puede crear un documento separado y vincularlo.

De esta manera, puede generar fácilmente la documentación como una página web o como un PDF, y se mantiene consistente con el código. El uso de algunas etiquetas artificiales será muy difícil de mantener e incluso más difícil de entender para los no iniciados.