ドキュメントでコードの特定の領域を参照するにはどうすればよいですか？

プロジェクトを離れようとしています。行く前に、上司からコードの文書化を求められました（あまり文書化していません）。大したことではなく、プロジェクトはそれほど複雑ではありません。しかし、私は自分のドキュメンテーションの中で、「XYZの行でそのようなことが起こることに気づく」と言いたい場所を見つけています。

この場合、コードの1行を追加または削除するとすぐにドキュメントが古くなるため、特定の行番号を参照しても意味がありません。行番号で参照せずに特定のコード行を参照するためのベストプラクティスはありますか？

私は次のようなコメントでコードを散らかすことを検討しました：

/* linetag 38FECD4F */

ここで、「38FECD4F」はその特定の行の一意のタグです。次に、「 '38FECD4F'とタグ付けされた行で、そのようなことが起こることに注意してください」というドキュメントを挿入できます。

他のアイデアは？コードユニットの特定の部分よりも全体としてドキュメント化する方が一般的には良いと思いますが、この特定のプロジェクトの場合、手続き型コードの長い列があり、小さいユニットにリファクタリングされたことはありません。

私がそれを正しく理解していれば、あなたには独特の問題があるようです。あなたがしたいことは、同じコードの他の部分に書かれているコメントの特定のコード行を参照しています。

私は通常、他の場所に書かれたコメントでexect行＃を参照する必要があるようなシナリオに出くわすことはありません。

私はこれを行うための標準的な方法を知りません-しかし私の頭の上から...

コードの一部、つまりコンテキストを介してコードの一部を参照できます。

func1（）の定義の上で、そのようなことが起こることに注意してください。

recordXYZItrを反復するforループの直後に、メソッドgc（）も呼び出していることに注意してください。

注意：メソッドyahoo（）では、変数PQの宣言の直後に、AとBの値も入れ替えているため、そこでmapABCオブジェクトもコピーする必要があります。

別の方法は、説明タグを追加することです。のようなものの代わりに、または38FECD4Fと言ってから、別の場所でそれを参照できます。Some XYZ implementationBUGFIX 1474

それはコードがどのように書かれたかに大きく依存します、そしてそれがあなたがここにしていない多くのリファクタリングを引き起こすかもしれないことを私は理解しています。

しかし...特定のコード行をユニット全体として参照する必要がある場合、それは抽象的な操作を表すいくつかのコードであり、したがって独自のメソッド/関数でリファクタリングできるということではないでしょうか？メソッドに入ったら、それはかなり簡単です。単に参照してください。namespace.class.methodもちろん、それは、非常に小さく、約5〜10行またはそれ以下のメソッドを持つことを意味します。Doxygenを使用すると、ドキュメントをメソッドの上に置くことができ、メソッド/クラス/名前空間の名前と常に同期します。

いくつかのコード外部ドキュメントからコードへのリンク以外は、別のアプローチを取ることをお勧めします。

1. doxygenなどのツールを使用して、コードにコメントを追加します。

2. （新しく作成された）コードのドキュメント内で適切ではない概念をより詳細に説明する必要がある場合は、いつでも別のドキュメントを作成してそれにリンクできます。

これにより、ドキュメントをWebページまたはPDFとして簡単に生成でき、コードとの整合性が保たれます。一部の人工タグを使用すると、維持するのが非常に難しくなり、初心者にとって理解がさらに難しくなります。