Hallo,
wie dokumentiert ihr Entwurfsentscheidungen, die sich auf ein Detail beziehen und möglicherweise für Entwickler wichtig sind, die den Code weiterentwickeln?
Ich habe z. B. eine Methode parse(String content), die auch parse(Reader content) heißen könnte. Ich habe mich nun aus einem bestimmten Grund für die Verwendung von String und den Verzicht auf die Abstraktion "Reader" entschieden. Den Grund für diese Entscheidung möchte ich Dokumentieren und könnte ihn dazu in einen JavaDoc-Kommentar schreiben, aber den Nutzer der API wird das vermutlich wenig interessieren. Also wäre wohl ein normaler Kommentar im Code besser. Oder würdet ihr lieber ein externes Dokument pflegen? Aber da sehe ich eher die Gefahr, dass sich Dokumentation und Code voneinander entfernen.
Christian
wie dokumentiert ihr Entwurfsentscheidungen, die sich auf ein Detail beziehen und möglicherweise für Entwickler wichtig sind, die den Code weiterentwickeln?
Ich habe z. B. eine Methode parse(String content), die auch parse(Reader content) heißen könnte. Ich habe mich nun aus einem bestimmten Grund für die Verwendung von String und den Verzicht auf die Abstraktion "Reader" entschieden. Den Grund für diese Entscheidung möchte ich Dokumentieren und könnte ihn dazu in einen JavaDoc-Kommentar schreiben, aber den Nutzer der API wird das vermutlich wenig interessieren. Also wäre wohl ein normaler Kommentar im Code besser. Oder würdet ihr lieber ein externes Dokument pflegen? Aber da sehe ich eher die Gefahr, dass sich Dokumentation und Code voneinander entfernen.
Christian
