|
Was gehört alles in eine richtige Dokumentation?
Hallo alle zusammen, mich würde es interessieren von euch langjährigen Entwicklern mal zu erfahren was denn alles so in eine ordentliche Dokumentation rein gehören sollte. Habe bisher noch keine erstellt und würde mich über Beispiele & Leitfäden freuen.
|
AW: Was gehört alles in eine richtige Dokumentation?
Tach,
präzisier bitte mal: was für ne Dokumentation (komplette Software, Entwicklerlibs,..)? Für wen soll die sein (Anwender, Entwicklerkollegen, Nachfolger,...)? |
AW: Was gehört alles in eine richtige Dokumentation?
Zitat:
Komplette Software, soll für andere Entwicklerkollegen / Projektmanager sein. |
AW: Was gehört alles in eine richtige Dokumentation?
Zitat:
MaBuSE |
AW: Was gehört alles in eine richtige Dokumentation?
Hallo,
- Schritt für Schritt Anleitung der Bedienung der Software - Bei Softwareentwicklungssystemen genügend Beispiele, die möglichst alle Faähigkeiten des Entwicklungssystems abdecken. Plus eine ausführliche Hilfe für alle Prozeduren, Funktioen, Klassen, Methoden,... - Verständliche Anleitung zur Benutzung von Zusatztools. - Das heißt aber bei Kommandozeilenprogrammen dann auch: jede Option in ihrer Bedeutung genau erklären Genaue Angabe, in welcher Reihenfolge die Optionen angegeben werden müssen oder besser noch das Tool so programmieren, das die Reihenfolge der Optionen egal ist. - Für diesen Fall auch Beispiele für die Verwendung des Kommandozeilenprogrammes. Bei Gui Programm: - sinnvolle Voreistellungen - wiederum Erklärung aller auswählbaren Optionen mit deren Bedeutung - Auch hier Beispiele mit verschiedenen Einstellungen. Ich hoffe, das hilft erst mal. Inzwischen ist mir jemand zuvor gekommen. Der hat schon alles Wichtige zusammengefasst. |
AW: Was gehört alles in eine richtige Dokumentation?
Gibt es freie Software die gut zum erstellen von Programmabhängigkeiten geeignet ist?
|
AW: Was gehört alles in eine richtige Dokumentation?
Zitat:
(bzw. Im Zitat unten) Zitat:
|
AW: Was gehört alles in eine richtige Dokumentation?
Zitat:
|
AW: Was gehört alles in eine richtige Dokumentation?
Zitat:
Das Tool kannst Du Dir auch ansehen:  http://www.delphipraxis.net/internal...ct.php?t=87932Zitat:
(Es gibt auch eine kostenlose Version) Es wird auch die Struktur der Objekte sichtbar. Richtig sinnvoll ist es allerdings erst, wenn der Programmierer auch Kommentare in den Quellcode geschrieben hat. Diese werden von Docomatic verwendet. -> Die Delphi Hilfe ist auch mit Doc-O-Matic erstellt worden. (Zumindest die von D2007, bei den aktuellen Versionen weiss ich es nicht). ESS Model sieht ein wenig aus die Modelansicht von Delphi. http://essmodel.sourceforge.net/Dependency Walker Um die Abhänigkeiten der Exe anzusehen: (also welche *.dll Dateien werden benötigt) http://www.dependencywalker.com/ |
AW: Was gehört alles in eine richtige Dokumentation?
Zitat:
Dabei können auch Klassen-, Objekt- und Sequenzdiagramme entstehen, die man dann der Dokumentation hinzufügen kann. Außerdem man kann dabei auch den Quelltext kommentieren, um später daraus Dokumentation zu generieren. Allerdings sollte man dann vielleicht im Kommentar anmerken, wenn es keine gesicherte Erkenntnis darstellt. |
AW: Was gehört alles in eine richtige Dokumentation?
Die Antwort auf alle Fragen in der Softwareentwicklung: "It depends" bzw. "kommt drauf an".
Zu Dokumentation hat fast jeder eine Meinung. Und je nachdem, wen man fragt wird man *sehr* unterschiedliche Antworten erhalten. Fakt ist: Eine pauschale Antwort gibt es nicht. Demnach musst du die Frage für dich beantworten. Dabei solltest du folgendes bedenken: - Wer soll die Doku lesen? Und was erwarten diese? Doku ist mit Sicherheit falsch, wenn sie an den Anforderungen der Stakeholder vorbei geht. Und das kann je nach Projekt sehr unterschiedlich sein. - Doku ist kein Selbstzweck. Je mehr du davon hast, desto aufwendiger ist es, sie zu pflegen. Und veraltete Doku ist i.d.R. schlechter als gar keine. - Je näher die Doku am Code ist (rein räumlich gesehen), desto wahrscheinlicher ist, dass sie gepflegt wird. Selbsterklärender Code > Kommentare im Code > Doku mitversioniert im selben Repository > Doku außerhalb des Repos > Doku auf Paper. - Doku, die keine neue Info hat, ist kontraproduktiv. Doku zu dem Konstruktor, die sagt "Create erzeugt ein neues Objekt" oder noch besser "Konstruktor der Klasse" ist sinnloses Gebabbel und sollte man unterlassen. - Je mehr Stakeholder du hast, desto mehr Doku ist nötig. Schreibst du ne API für hunderte anderer Entwickler, brauchst du mehr Doku, als wenn du der einzige bist, der das unter die Finger kriegt. Wenn sich das Entwicklerteam ständig ändert, brauchst du mehr Doku, als wenn du ein festes, unveränderliches Team hast. - Je mehr sich der Code ändert, desto schneller veraltet Doku und desto weniger solltest du haben. Abstrakte Basisklassen musst du eher beschreiben als temporäre Implementierungen, die beim nächsten Refactoring eh wieder wegfallen. Ebenso ist es sinnvoller, die grobe Architektur zu dokumentieren (weil die sich nur langsam ändert), als irgendwelche privaten Methoden, die eh ständig umgeschrieben werden. Dokumentiere Abstraktes und Allgemeines eher als konkretes. - Doku macht nur Sinn, wenn sie auch gelesen wird. Wenn sie zu detalliert ist und niemand den Detailgrad braucht, ist das vergeudete Zeit. Diagramme sind gut. Denn damit kann man Zusammenhänge übersichtlich zeigen, die man im Code nie sehen würde, weil man im Code quasi immer mit der Lupe vor nem monumentalen Wandteppich steht. Diagramme, die aber nicht übersichtlich sind, sind wertlos. - Wenn du wissen willst, was gute Doku ist, guck dir schlechte an. - Besser noch: frag die Stakeholder, die die Doku lesen sollen nach Beispielen für gute und schlechte Doku. Frag sie, was sioe ganz konkret brauchen und erwarten. Frag sie, was sie haben wollen und wie sie die Doku benutzen würden. Ganz konkret die Personen, die das betrifft. Wir hier können nur Anhaltspunkte liefern und ggf. aus dem Nähkästchen plaudern. Aber wir können hier keine Abschließende Antwort liefern, weil wir dein Projekt nicht kennen. - ... mfg Christian |
AW: Was gehört alles in eine richtige Dokumentation?
Zitat:
|
AW: Was gehört alles in eine richtige Dokumentation?
Hi!
Oft schon die Basics - Zugangsdaten und bei externen die Ansprechpartner. Welche Versionen kamen zum Kunden. Welche Versionen sind wo archiviert. Dann der Quellcode. Wenn eine Datenbank genutzt wird, dann ein ER Diagramm. Welcher Aufwand wurde betrieben, damit man bei weiteren Projekten schauen kann, ob man im Budget war. |
AW: Was gehört alles in eine richtige Dokumentation?
Laut
Uncle Bob ist eine Software ausreichend dokumentiert wenn zu allen Methoden/Funktionen Testfälle/Unit-Tests vorliegen. Grüße Klaus |
AW: Was gehört alles in eine richtige Dokumentation?
Such einfach bei den "GROßEN"...:-D
Die haben verschiedene Textepassagen meistens... per "RA" überprüfen lassen...:lol: |
AW: Was gehört alles in eine richtige Dokumentation?
In der Doku? :shock:
|
AW: Was gehört alles in eine richtige Dokumentation?
Oiiihhh,habe gepennt.:cyclops:
Naja mein Spruch unten drunter gilt leider auch für mich....:-D:-D:-D |
AW: Was gehört alles in eine richtige Dokumentation?
Gibt es hier im Forum noch Beispiele in Form von Pdf einer richtigen Software Dokumentation wo auf Funktionen / Parameter von Klassen / Methoden eingegangen wird?
|
AW: Was gehört alles in eine richtige Dokumentation?
Sichwort Dokumentation
Egal ob du jetzt Object Pascal, C/C++, Java, Groovy, Velocity, HTML oder JavaScript Programmierst... Kommentier wenigstens was eine Methode oder Funktion machen soll!!! |
AW: Was gehört alles in eine richtige Dokumentation?
Zitat:
z.B. http://docs.embarcadero.com/products...hivclwin32.pdf( Achtung: das PDF hat 25622 Seiten und ist ca. 400 MB Groß :roll: ) Das ist die Hilfe zur VCL von D2007 als PDF. Diese wurde die die Online-Hilfe mit Doc-O-Matic erstellt. (Habe ich schon weiter oben beschrieben) Apropos Delphi Dokumentation / Hilfe: Das hier ist eine ganz gute Übersicht http://docs.embarcadero.com/products...udio/index.php |
AW: Was gehört alles in eine richtige Dokumentation?
Zitat:
|
AW: Was gehört alles in eine richtige Dokumentation?
Liste der Anhänge anzeigen (Anzahl: 1)
Zitat:
Wenn man Units schreibt, die auch von anderen verwendet werden sollen, muß eine vernünftige Dokumentation her. Beisp.: Der Code folgender Funktion ist simpel und relativ kurz. Trotzdem gibt es im interface Teil der Unit Kommentare dazu.
Delphi-Quellcode:
Im implementation teil stehen dann normalerweise keine Kommentare mehr. Es sei denn es wird etwas gemacht, was auf den ersten Blick nicht ersichtlich ist (Trick, Workarround, ...) das wird natürlich direkt im Code kommentiert.
// Ändert Enabled von allen Controls die AControl als Parent haben (rekursiv)
// Parameter: AForm: Formular auf dem der Container AControl liegt // AControl: Container, der andere Controls beinhaltet // AValue: True=alle werden Enabled <p>False=alle werden Disabled procedure SetEnabledRec(AForm: TComponent; AControl: TControl; AValue: Boolean); Docomatic macht übrigends auf dem Kommentar oben bei und folgenden Text in der Systemdokumentation: |
AW: Was gehört alles in eine richtige Dokumentation?
Zitat:
- Dennoch sollten auch und gerade bei APIs die Bezeichner gut gewählt sein und die Doku im Idealfall "unnötig" machen. - Bei APIs sollte man auch Kleinkram, Randbedingungen, etc. dokumentieren. Denn darauf kommt es an. Ein pauschales "Mach an jede Methode Doxygen/Docomatic (o.ä.) dran" ist aber kontraproduktiv. Ich hab viel zu viel Doku gelesen wie
Delphi-Quellcode:
Solche Doku ist nicht nur nicht hilfreich. Sie ist dumm. Ich darf das sagen, denn ich hab sowas schon zur Genüge selbst produziert. Falsch verstandener Zwang zur Doku führt zu schlechter Doku. Die Delphi-Hilfe zur RTL, etc. zeigt, wie man gute Doku schreibt. Aber das ist auch eine API die von tausenden Entwicklern benutzt wird. Da darf kein Zweifel herrschen. Aber, wenn man sich selbst auferlegt für jede private Methode n Kommentar zu schreiben, macht man *definitiv* etwas falsch.
/// Gets the value.
/// @Retrurn the value function GetValue: Integer; Zitat:
Aber wenn du schon ein Beispiel lieferst, will ich es auch nutzen. Denn es unterstreicht meine Aussage von oben. Wenn ein Kommentar nötig ist, bedeutet das in 98,57% aller Fälle, dass entweder der Name falsch ist oder die Methode tut zu viel/das Falsche und sollte aufgeteilt werden bzw. etwas anderes tun. Sei mir nicht böse, wenn ich dein Beispiel jetzt total zerpflücke:
Delphi-Quellcode:
Dann nenn die Methode auch so: // Ändert Enabled von allen Controls die AControl als Parent haben (rekursiv)
Delphi-Quellcode:
. Und schon hat sich der Kommentar erübrigt. Ja, der Name ist lang. Aber du musst ihn nur einmal tippen. Die Code-Vervollständigung sollte ja den Rest übernehmen. Dafür sparst du dir das Nachgucken in der Doku und dein Code wird deutlich besser lesbar.
SetEnabledOfChildControlsRecursively
Delphi-Quellcode:
- Wenn das ein Formular sein muss, sollte auch der Typ TCustomForm sein.// Parameter: AForm: Formular auf dem der Container AControl liegt - Und viel wichtiger: Der Parameter sollte gar nicht nötig sein ( IAP).
Delphi-Quellcode:
- Ich bin nicht mehr ganz so firm in der VCL, aber ist es nicht TWinControl, das ein Container sein kann? Korrigiere mich, wenn ich falsch liege. In dem Fall sollte der Typ des Parameters TWinControl sein.// AControl: Container, der andere Controls beinhaltet - Angenommen, da stände TWinControl. Damit wäre der Kommentar redundant zur Doku von TWinControl. Also ist der in der Form überflüssig.
Delphi-Quellcode:
Wenn der Name der Methode wie oben vorgeschlagen ist, ist der Kommentar hier auch überflüssig, denn er wiederholt die Funktionsweise der Methode. Du wolltest AValue erklären. Die Korrekte Beschreibung wäre "Der Wert auf den die Eigenschaft Enabled von allen ChildControls gesetzt werden soll". Und das sagt bereits der Name.// AValue: True=alle werden Enabled <p>False=alle werden Disabled
Delphi-Quellcode:
"Rec" ist zwar kurz, aber mehrdeutig. Record? Recording? Recorded? Recently? Anders als Dec und Inc ist Rec nicht unbedingt eine allgemein bekannte Abkürzung. Und Abkürzungen in Bezeichnern, die nicht eh klar sind, sind schlecht.procedure SetEnabledRec(AForm: TComponent; AControl: TControl; AValue: Boolean); Jetzt mal angenommen, das sollte Teil einer API für viele Entwickler sein. So, wie die RTL eben. In dem Fall fehlen mir wichtige Infos. Du hast die Methode nicht vollständig beschrieben: - Wird Enabled von AControl auch gesetzt oder nur von den Kindern? - Wird die Parent- oder die Owner-Hierarchie der Komponenten als "ist enthalten in" betrachtet. Ich gehe mal fest davon aus, du meinst letztere. Wenn du aber API schreibst, solltest du da genau sein. - Was passiert, wenn AForm und AControl nicht zusammen passen? Wie oben geschrieben solltest du das eh verhindern. Wenn du es nicht verhindern kannst -- warum auch immer --, musst du es dokumentieren. Man kann jetzt noch weiter überlegen. Will man tatsächlich einen Boolean übergeben? Oder will man nur alle entweder an oder aus knipsen. Wenn ersteres hinreichend selten ist, kann man auch überlegen, die Methode zu teilen:
Delphi-Quellcode:
und
EnableChildControlsRecursively(TWinColntrol)
Delphi-Quellcode:
. Das würde das noch einfacher machen, das zu benutzen. Genau genommen könnte man die Methoden im Zweifel einfach zusätzlich anbieten. Damit stellt sich die Frage gar nicht mehr. Also auf jeden Fall teilen.
DisableChildControlsRecursively(TWinControl)
Als nächstes bemerke ich, dass dadurch, dass das Recursively ausgeschrieben ist und nur noch ein Parameter da ist, das "ChildControls" fast schon wieder überflüssig wird. Also entferne ich das wieder (Refactoring ist eben ein iterativer Prozess). Damit wäre ich bei
Delphi-Quellcode:
und
EnableRecursively(TWinColntrol)
Delphi-Quellcode:
. Ich glaub, jetzt bin ich endlich zufrieden.
DisableRecursively(TWinControl)
Und jetzt vergleichen wir mal:
Delphi-Quellcode:
mfg
SetEnabledRec(Self, panel1, false);
// vs. DisableRecursively(panel1); Christian P.S.: Hier ein sehr schönes Video, das zeigt, wie man u.a. durch Entfernung von unnötigen Kommentaren Code besser macht: http://www.youtube.com/watch?v=aWiwDdx_rdo[1] Davon abgesehen sollte quasi jede Methode kurz sein. Aber das steht hier nicht zur Debatte. |
AW: Was gehört alles in eine richtige Dokumentation?
Zitat:
Ich hatte eine Funktion gesucht, die nicht zu viel Kommentar / Dokumentation hat. Diese Funktion ist Teil einer Bibliothek, die schon seit mehr als 15 Jahren in Benutzung ist. Sie wird von ca. 40 Entwicklern in unzähligen Projekten verwendet. Es traut sich einfach niemand so alte und häufig benutze Funktionen "anzufassen". Aus diesem Grund wurde sie vor ein paar Jahren wenigstens dokumentiert ;-) Ich glaube es gibt sogar eine Funktion
Delphi-Quellcode:
, welche die alte aufruft :shock:
DisableRecursive(Form.Control);
In deinen Ausführungen gebe ich dir größtenteils (ich bin kein Fan von sehr langen Namen) Recht. Der Entwickler der Funktion würde das heute wahrscheinlich auch anders machen. Trotzdem würde ich auch bei einer eindeutig benamten Funktion, mit eindeutig benamten Parametern, eine Dokumentation erwarten. Auch wenn in der Dokumentation "nur" in Prosa das steht, was man beim Namen der Funktion erwarten würde. Ich bin auch Fan von Änderungshistorien. z.B: In der Funktion hat sich ab 01.01.2013 folgendes Verhalten geändert: ... Oder auch der Autor und das Erstellungsdatum einer Funktion. Diese Informationen bekommt man zwar auch z.B. über ein Blame in git, aber solche Dinge gehören für mich einfach in eine Dokumentation. (Zumindest bei APIs) |
AW: Was gehört alles in eine richtige Dokumentation?
Zitat:
Zitat:
Delphi-Quellcode:
Wozu also jetzt noch Kommentare? ;-)
SetEnabledOfChildControlsOnForm(aForm : TComponent; aParentControl : TControl; aValue : Boolean);
|
AW: Was gehört alles in eine richtige Dokumentation?
Nicht
Delphi-Quellcode:
:?:
SetChildControlsOnFormEnabledRecursively(aForm: TCustomForm; aParentControl: TWinControl; Enabled: Boolean);
|
AW: Was gehört alles in eine richtige Dokumentation?
Zitat:
|
AW: Was gehört alles in eine richtige Dokumentation?
...Hier stand der Beginn einer kleinen Auseinandersetzung, der jedoch von MaBuSe per PN im Keim erstickt wurde, weswegen das auch nicht hierhin gehört...
Ich fand es nur lustig, das r2c2's (korrekte) Aussage, sprechende Namen seien besser als Kommentare neben dein Paradebeispiel schlechter Nomenklatur zu stellen. Ich meine, das muss Dir doch selbst aufgefallen sein, das der Name ähem.. du weisst schon. Auto-an-Wand. Übrigens, falls es dich interessiert: Ein Methodenname darf gerade nicht den Algorithmus ('Rekursiv') wiederspiegeln, sondern kurz und knapp erklären, was die Methode anstellt. 'SetEnabledRec' ist Schrottungenau, 'SetEnabledStateOfChildControls' nicht. Ob das rekursiv, iterativ oder sonst was ist, ist irrelevant. Wir können natürlich auch richtig albern werden, und das Teil 'SetEnabledStateOfChildAndTheirChildsAndTheirChild sAndSoOnControls' nennen, aber -hey- WTF. Eine API zu dokumentieren, ist notwendig und vollkommen unabhängig von meinem Einwand (ich schrieb eigentlich nichts davon). WEnn Du deinen API-Funktionen, oder wer auch immer die so genannt hat, einfach aussagekräftige Namen gibst, wird eine Dokumentation schnell überflüssig. Das merkst Du daran, das Du für die Beschreibung der Methode fast genau die Worte verwendest, die im Namen der Methode selbst stecken:
Delphi-Quellcode:
Es gibt Kollegen, die sich weigern das so hinzuschreiben. Weil es so einfach nur kreuzdämlich ist. Und eine Methode nur um des Kommentieren willens zu kommentieren, erinnert mich an die Schildbürger.
// Creates a Form of type aFormClass
procedure UIManager.CreateForm(aFormClass :TFormClass) Dessenungeachtet sind Konstrukte wie dieses 'Ich setze Enabled gleich für alle Childcontrols' eigentlich kein Fall für eine API, denn eine API soll ja nur die Basisfunktionen bereitstellen und keine Superdupersonderichmachdasallesfürdich-Funktionen. Aber das steht auf einem anderen Blatt. --- und hier stand auch noch überflüssiges Zeugs--- |
AW: Was gehört alles in eine richtige Dokumentation?
Zitat:
Zitat:
Zitat:
Zitat:
Zitat:
- "gehört für mich einfach rein" ist kein Grund. Wenn ich bemerke, dass ich für eine Meinung keine Gründe habe, stelle ich diese in Frage. Ich kann das nur empfehlen, denn es ist augenöffnend. - Was bei APIs sinnvoll sein kann (aber nicht muss): Dokumentieren, ab welcher Version etwas etwas neu eingeführt worden ist. So kann man beispielsweise nachgucken, ob Code noch mit ner alten Bibliothek laufen würde. Sowas wie "Läuft meine Komponente auch noch unter Delphi 7?" - Ähnlich: Breaking changes: Läuft mein Code mit der neuen API-Version noch? Warum sage ich eigentlich immer "sinnvoll sein kann"? Ganz einfach: Wie in meinem ersten Beitrag hier im Thread geschrieben, kommt es immer auf die Stakeholder drauf an. Doku machen wir aus einem Grund. Nämlich, dass sie gelesen wird. Doku macht Arbeit. Arbeit zu schreiben, Arbeit zu pflegen und ja, auch Arbeit zu lesen. Wenn ich jetzt Doku habe, die keinen Mehrwert bietet, sondern genauso schlau bin, nachdem ich sie gelsenen habe, wie zuvor, hätte ich mir gar nicht erst die Mühe machen müssen, sie zu lesen. Es ist frustrierend, Doku zu lesen, die keinen Mehrwert bietet und nich frustrierender, wenn man sich vor Augen hält, dass jemand Zeit darin investiert hat, mir dadurch Zeit zu rauben... Zitat:
- Dass sie auch Leute verstehen, die nicht wissen, dass "Absolutwert" ein Synonym für die Betragsfunktion ist - Dass sie keine Infos wiederholen, die in der Signatur stehen ("X ist ein Ausdruck des Typs Integer oder Real.") - Dass Randfälle erklärt werden. Was passiert, wenn man NaN übergibt? Exception oder auch NaN? Das wären Infos, die einen Mehrwert bieten. Zitat:
|
AW: Was gehört alles in eine richtige Dokumentation?
Zitat:
Ach, und die Sache mit der Rekusivität im Methodennamen kann man so sehen, muss man nicht, aber dein Einwand ist schon ok. |
AW: Was gehört alles in eine richtige Dokumentation?
Zitat:
Zitat:
Dokumentation ist aufwendig, also möchte man nicht für jede Zielgruppe eine eigene Doku schreiben. Man erstellt Doku, die von mehreren Zielgruppen verwendet werden kann. z.B. von Prüfern der externen Revision Die Dokumentation einer API muss (z.B. für die Prüfer) verschiedene Kriterien erfüllen. z.B. wird Erwartet, dass Funktionsänderungen in den Klassen / Methoden mit Datum und Version beschrieben werden. (ab v2.0.1 (01.01.2013) wird nicht mehr kaufmännisch, sondern mathematisch gerundet.) Zitat:
Aber, wenn eine Funktion (nennen wir sie GetDefaultColor) eine Farbe zurückgibt (z.B. Blau) und das auch dokumentiert ist, sich ändert und nun eine andere Farbe zurückgibt (z.B. Grün), dann würde ich mir in der Doku folgendes wünschen:
Code:
Das macht vor allem dann Sinn, wenn aus Gründen der Wartbarkeit nur eine (aktuelle) Doku vorgehalten wird, die API aber leider auch in älteren Versionen verwendet wird.
...gibt die Farbe Blau zurück.
...ab v2.0 gibt die Funktion die Farbe Grün zurück. Zitat:
Ich bin auch kein Fan von "Warum?" -> "Das haben wir schon immer so gemacht!" Zitat:
Um die Arbeit an der Doku zu minimieren, {zweckent|ver}wenden wir die Kommentare im Quelltext (im interface-Teil) zur Erstellung der Systemdokumentation. Das hat sich als praktikabel erwiesen. Das ist Geschmackssache. Zitat:
Ich scheine bei der Wahl meiner Beispiele kein glückliches Händchen zu haben. Zitat:
Wobei das auch ungenau formuliert ist, da es ja nur bedeutet, dass die Menge berechenbar ist. (wenn ich mich recht erinnere) Aber ich hoffe man versteht es trotzdem. |
AW: Was gehört alles in eine richtige Dokumentation?
Zitat:
Zitat:
Zitat:
Zitat:
Zitat:
|
AW: Was gehört alles in eine richtige Dokumentation?
Zitat:
So wie man es vom MSDN kennt, also eine Angabe für welche Version das gültig ist. Denn vorallem für Komponentenentwickler wäre das bestimmt eine schöne Erleichterung. (eventuell das Alte auch nicht sofort löschen ... nur in der aktuellen Hilfe nicht direkt verlinken) |
AW: Was gehört alles in eine richtige Dokumentation?
Zitat:
Mir ist auch klar das man einfache Methoden nicht Kommentieren muss/sollte um nicht einen Unleserlichen Kommentar zu gestallten. Aber einfach mal so ne kleine Frage in den Raum... Wie gut könnt ihr sehr schnell etwas ändern wenn eine Methode geschrieben wurde ohne das irgendwer es für nötig gefunden hat zu erklären woher z.B. eine GUID (in Intrexx Standard und in Delphi auch verfügbar)stammt? Kann sein das man die GUID schnell findet aber ich wünsche viel Vergnügen beim Suchen wenn die GUID zerschossen wurde... Dann hat man das unschöne Vergnügen folgende Dinge zu tun:
Applikation vor sich hat würde man sich Wünschen man könnte nur dem Beschrieb vom Kommentar folgen :wall: Das Mass halten gehört wohl zu denn Schwierigsten Herausforderungen des Lebens... Von daher ist niemand Perfekt aber ein Code komplett ohne Kommentar zu erstellen ist ein (schwer)Verbrechen |
AW: Was gehört alles in eine richtige Dokumentation?
Zitat:
Was ich meine, ist die Frage, ob selbsterklärende API-Funktionen eines redundanten Kommentares bedarf. Wir hatten das Thema lustigerweise heute im Team und als ich anmerkte: "Ja 'CreateForm' mit 'Creates a Form' zu dokumentieren, ist heute blödsinnig, aber Kommentare leben und ein existierender Kommentar wird eher erweitert, als ein nicht vorhandener" Die Argumentation stieß auf Zustimmung |
AW: Was gehört alles in eine richtige Dokumentation?
Zitat:
Zitat:
Zitat:
Je mehr Kommentare da sind, desto mehr Arbeit ist es sie zu pflegen und desto weniger wird es gemacht. Deshalb ist es nicht gut, unnötige Kommentare zu haben. Zudem: Wenn du nur eine Stelle hast, die du nicht selbsterklärend machen konntest, sodass dort ein Kommentar nötig ist, dann wird dieser eine Kommentar herasusstechen. Man merkt gleich: "Oh, das ist eine komplizierte Stelle, da muss ich aufpassen, wenn ich was ändere und ich muss den Kommentar lesen und ggf. anpassen". Wenn du überall Kommentare hast, hast du diesen Effekt nicht. Kommentare sind wie Antibiotika. Wenn du sie brauchst, sind sie gut und helfen dir. Es ist aber keine gute Idee, präventiv täglich welche zu nehmen, wenn man sie nicht brauchst. Kommentare sind nicht inhärent gut. Sie sind ein manchmal nicht zu umgehendes Übel. |
| Alle Zeitangaben in WEZ +1. Es ist jetzt 02:13 Uhr. |
Powered by vBulletin® Copyright ©2000 - 2024, Jelsoft Enterprises Ltd.
LinkBacks Enabled by vBSEO © 2011, Crawlability, Inc.
Delphi-PRAXiS (c) 2002 - 2023 by Daniel R. Wolf, 2024 by Thomas Breitkreuz