Kommentare für geometrische Berechnungen

[Maxi]

Hallo!

Wie kommentiert man am besten, wenn man zum Erklären eine Skizze gut verwenden könnte? Bspw sowas:

/*
             * Nun noch dritten Punkt des Bogens berechnen, damit er erstellt werden kann.
             * durch geometrische Überlegung gilt folgendes:
             * 
             *   u
             * ------>p1
             *          \    p3
             *           \  /w
             *           v\/
             *             \
             *              \
             *               p2
             *             
             * Der Bogen liegt durch p1, p3, p2 in der Reihenfolge. w muss senkrecht auf v stehen, da w auch durch
             * durch Mittelpunkt des Bogens geht. Es gilt:
             * w=v x (u x v)
             * 
             * Das wird dann noch normalisiert und dann vom Mittelpunkt mit Länge des Radius abgetragen.
             * */

Die Skizze dort kann ziemlich aufwändig werden, wenn es um kompliziertere Dinge geht, und irgendwann kann man es mit Ascii-Art auch nicht mehr ausdrücken.
Wie könnte man das besser lösen? Extern Bilder zu malen und zu verlinken ist irgendwie auch blöd, da die dann noch schneller zum quellcode inkonsistent werden könnten.
Habt ihr da andere MEthoden?

Liebe Grüße, Max

[marco.b]

Kommentare werden zum Quellcode ebenso inkonsistent, wie eine externe Dokumentation. Letzteres würde ich in solch einem Fall bevorzugen, geometrische Überlegungen gehören meines Erachtens nicht in den Quellcode.

[Emacs-User]

Man kann mit Ascii-Art schon einiges machen, es empfiehlt sich dafür natürlich ein Programm das einem das Zeichnen wie in einer Bitmap ermöglicht. Emacs besitzt so einen Modus, nennt sich artist-mode

[hustbaer]

marco.b schrieb:

Kommentare werden zum Quellcode ebenso inkonsistent, wie eine externe Dokumentation.

Die Chance, dass Kommentare angepasst werden (oder ggf. ganz gelöscht, wenn sie hinfällig sind), ist IMO deutlich höher, als dass externe Dokumentation angepasst wird.

[marco.b]

@hustbaer: Bei Hobbyprogrammierern vielleicht. In professionellen Teams gibt es sowas wie Richtlinien.

Im Beruf sollte man sich gewisse Abläufe verinnerlichen können - da hilft die Ausrede, "ja, ich hab halt nicht dran gedacht, da hätte ich ja in einen anderen Ordner klicken müssen" nicht unbedingt viel. Abgesehen davon stören riesige Ascii-Art Kommentare sowas von widerlich den Lesefluss, dass es kaum erträglich wäre.

[knivil]

Benutze einfach die Sprache der Mathematik. Auch bei komplizierten Sachen war durch sie meine Kommentare immer kurz und praezise. Zeichnungen sind ueberfluessig, da sie nur die Mathematik erklaeren, nicht aber die Funktion.