Como se referir a áreas específicas de código na documentação?

Estou prestes a sair de um projeto e, antes de partir, meu chefe me pediu para documentar o código (não o documentei muito bem). Não é grande coisa, o projeto não é terrivelmente complexo. Mas estou encontrando lugares em minha documentação onde gostaria de dizer: "Observe na linha XYZ que isso e aquilo acontece".

Nesse caso, não faz sentido se referir a um número de linha específico, pois adicionar ou excluir uma única linha de código desatualizará imediatamente a documentação. Existe alguma prática recomendada para se referir a uma linha específica de código sem se referir a ela pelo número da linha?

Eu considerei encher o código com comentários como:

/* linetag 38FECD4F */

Onde "38FECD4F" é uma tag exclusiva para essa linha específica. Então, posso colocar na documentação "Na linha identificada como '38FECD4F', observe que isso e aquilo acontece".

Alguma outra ideia? Eu sinto que geralmente é melhor documentar unidades de código como um todo, em vez de partes específicas delas, mas no caso desse projeto em particular, existem LONTAS faixas de código processual, que nunca foram refatoradas em unidades menores.

Se eu entendi direito, você parece ter um problema único. O que você deseja fazer se refere a uma linha específica de código nos comentários, escritos em alguma outra parte do mesmo código.

Normalmente, não encontro tais cenários em que preciso me referir a uma linha exata # em algum comentário escrito em outro lugar - geralmente o código é documentado exatamente onde está escrito.

Eu não conheço nenhuma maneira padrão de fazer isso - mas de cabeça para baixo ...

Você pode se referir a partes do código através do seu contexto - isto é, coisas ao seu redor.

Observe acima da definição de func1 () que tal e tal acontece

Observe que logo após o loop for que itera sobre recordXYZItr, também estamos chamando o método gc ()

Cuidado: No método yahoo (), logo após a declaração da variável PQ, também estamos trocando os valores em A e B, para que o objeto mapABC lá também precise ser copiado

Outra maneira é adicionar tags descritivas. Em vez de algo como 38FECD4F, você pode dizer Some XYZ implementationor BUGFIX 1474e, em seguida, consultar isso em outro lugar.

Depende muito de como o código foi escrito, e eu entendo que ele pode induzir várias refatorações que você não está aqui para fazer.

Mas ... se você precisar se referir a uma linha específica de código como uma unidade inteira, isso não significa que é algum código que representa uma operação abstrata e, portanto, pode ser refatorado em seu próprio método / função? Quando namespace.class.methodestiver em um método, é bastante fácil, basta consultar Naturalmente que significa ter métodos muito pequenos, com cerca de 5 a 10 linhas de comprimento ou até menos. Com o Doxygen, você pode colocar a documentação em cima do método, e ela sempre fica sincronizada com o nome do método / classe / espaço para nome.

Sugiro que você adote uma abordagem diferente, além de vincular de alguma documentação externa ao código:

1. adicione comentários ao seu código, usando uma ferramenta como doxygen .

2. se houver a necessidade de explicar algum conceito com mais detalhes do que o adequado na documentação do código (recém-criado), você sempre poderá criar um documento separado e vincular-se a ele.

Dessa forma, você pode gerar facilmente a documentação como uma página da Web ou como PDF, e ela permanece consistente com o código. O uso de algumas tags artificiais se tornará muito difícil de manter e ainda mais difícil de entender para os não iniciados.