Wie verweise ich in der Dokumentation auf bestimmte Codebereiche?

Ich bin dabei, ein Projekt zu verlassen, und bevor ich gehe, hat mein Chef mich gebeten, Code zu dokumentieren (ich habe nicht sehr gut dokumentiert). Es ist keine große Sache, das Projekt ist nicht besonders komplex. Aber ich finde in meiner Dokumentation Stellen, an denen ich sagen möchte: "Beachten Sie in Zeile XYZ, dass so und so etwas passiert."

In diesem Fall ist es nicht sinnvoll, auf eine bestimmte Zeilennummer zu verweisen, da das Hinzufügen oder Löschen einer einzelnen Codezeile die Dokumentation sofort veraltet. Gibt es eine bewährte Methode, um auf eine bestimmte Codezeile zu verweisen, ohne sie durch die Zeilennummer zu referenzieren?

Ich habe darüber nachgedacht, den Code mit Kommentaren wie:

/* linetag 38FECD4F */

Wobei "38FECD4F" ein eindeutiges Tag für diese bestimmte Zeile ist. Dann kann ich in die Dokumentation einfügen: "Beachten Sie in der Zeile '38FECD4F', dass dies und das passiert."

Irgendwelche anderen Ideen? Ich bin der Meinung, dass es im Allgemeinen besser ist, Codeeinheiten als Ganzes zu dokumentieren, als bestimmte Teile davon, aber im Fall dieses speziellen Projekts gibt es LANGE Schwaden von Verfahrenscode, die nie in kleinere Einheiten umgestaltet wurden.

Wenn ich es richtig verstehe, scheinen Sie ein einzigartiges Problem zu haben. Was Sie tun möchten, bezieht sich auf eine bestimmte Codezeile in Kommentaren, die in einem anderen Teil desselben Codes geschrieben sind.

Normalerweise stoße ich nicht auf solche Szenarien, in denen ich in einem an anderer Stelle geschriebenen Kommentar auf eine exakte Zeile # verweisen muss - im Allgemeinen wird Code genau dort dokumentiert, wo er geschrieben wurde.

Ich kenne keinen Standardweg, um das zu tun - aber auf den ersten Blick ...

Sie können Teile des Codes über seinen Kontext referenzieren - dh Dinge, die sie umgeben.

Beachten Sie über der Definition von func1 (), dass dies und das passiert

Beachten Sie, dass wir direkt nach der for-Schleife, die über recordXYZItr iteriert, auch die Methode gc () aufrufen.

Achtung: In der Methode yahoo () tauschen wir direkt nach der Deklaration der Variablen PQ auch die Werte in A und B aus, sodass das dortige mapABC-Objekt ebenfalls kopiert werden muss

Eine andere Möglichkeit besteht darin, beschreibende Tags hinzuzufügen. Anstelle von so etwas 38FECD4Fkönnen Sie Some XYZ implementationoder sagen BUGFIX 1474und dann woanders darauf verweisen.

Es hängt sehr davon ab, wie der Code geschrieben wurde, und ich verstehe, dass dies zu einer Reihe von Umgestaltungen führen kann, für die Sie nicht hier sind.

Aber ... wenn Sie sich auf eine bestimmte Codezeile als ganze Einheit beziehen müssen, würde dies nicht bedeuten, dass es sich um einen Code handelt, der eine abstrakte Operation darstellt und daher in einer eigenen Methode / Funktion überarbeitet werden könnte? Sobald es in einer Methode ist, ist es ziemlich einfach. Beziehen Sie sich namespace.class.methodnatürlich auf Methoden, die sehr klein sind, etwa 5-10 Zeilen lang oder sogar weniger. Mit Doxygen können Sie die Dokumentation über die Methode stellen, und sie bleibt immer mit dem Namen der Methode / Klasse / des Namespace synchron.

Ich schlage vor, Sie verfolgen einen anderen Ansatz als das Verknüpfen einer Code-externen Dokumentation mit Code:

1. Fügen Sie Ihrem Code mit einem Tool wie doxygen Kommentare hinzu .

2. Sollte es notwendig sein, ein Konzept detaillierter zu erläutern, als es in der Dokumentation des (neu erstellten) Codes angemessen ist, können Sie jederzeit ein separates Dokument erstellen und darauf verlinken.

Auf diese Weise können Sie die Dokumentation einfach als Webseite oder als PDF erstellen und sie bleibt mit dem Code konsistent. Die Verwendung einiger künstlicher Tags wird für Uneingeweihte sehr schwierig zu pflegen und noch schwieriger zu verstehen sein.