kommentieren code

Question

was ist die professionellste und informativste art der kommentierung von code. Gibt es irgendwelche Standards?

p.s. es muss nicht javadoc, nur Informationen über das, was zu umfassen - alle gemeinsamen Layouts etc

prost Jungs

Answer 1

Es gibt einen großen Unterschied zwischen dem Kommentieren von internem Methodencode und dem Kommentieren von APIs.

Bei Code sind mir bestimmte Vorgehensweisen oder Layouts nicht vertraut. "Gebrauche den gesunden Menschenverstand" ist der beste. Dokumentieren Sie nichts, was aus dem Code ersichtlich ist, sondern dokumentieren Sie alles, was nicht sofort klar ist. Und denken Sie daran, die eine Sache schlechter als Code ohne Kommentare ist Code mit veralteten Kommentaren. Mehr Kommentare bedeuten mehr Dinge, die aktualisiert werden müssen.

Für API-Dokumentation gibt es zwei Ansätze. Das Dokument-alles-in-Tonnen-von-Details (von Sun vorgeschlagen), und die agiler (schlagen Sie nur die wichtigen Teile vor). An vielen Stellen wird von Ihnen nicht erwartet, API-Inhalte zu dokumentieren, die aus der Signatur ersichtlich sind.

Während eine vollständige Dokumentation der Methode (der Sonne Ansatz) wichtig ist, um eine gut ausgearbeitete Spezifikation zu haben, zeigt meine Forschung, dass es schwieriger macht, wichtige Vorbehalte zu erkennen, wahrscheinlich zu mehr Fehlern führen.

Für APIs, siehe auch: Creating Great API Documentation: Tools and Techniques

Answer 2

Java hat definierten Code kommentieren Standards. Versuchen Sie diese http://www.oracle.com/technetwork/java/codeconv-138413.html

Answer 3

Ich denke, es kommt darauf an, Javadocs sind nett für größere Projekte. Wenn es etwas für eine kleine Projekt- oder Schulaufgabe ist, wird eine kleine Beschreibung vor dem Methodenkopf gut sein und vielleicht einige eingestreute Kommentare innerhalb der Methoden, falls Sie Dinge auf unorthodoxe Weise tun. Vor jedem von diesen würde ich empfehlen, dass Sie Ihren Methoden informative Namen sowie Variablen und Parameter auf diese Weise geben, ist es einfacher abzuleiten, was die Methode tut, als zu lesen und zu versuchen, genau herauszufinden, was jeder Parameter für usw. ist.

Answer 4

ich einmal Vorbedingungen zu verwenden, post-Bedingungen unterrichtet wurde, und kommentieren die Datenstruktur jedes Verfahren ändern wird. Das war in der Schule. Ich habe das in der Industrie noch nie gesehen.

Answer 5

1. Ich benutze, um Datei/META-INF/CHANGELOG zu erstellen und halten Sie es aktuell (z. B. 10.12.2010 Feature A hinzugefügt).
2. Ussualy Ich erstelle README im Quellordner und breafly beschreiben ganze Projekt darin (zum Beispiel: Projekt hat Feature A und diese Klassen behandeln Feature A. SubFeature SubA ändern Klasse Foo ändern ...)
3. In Kommentare versuchen um zu beschreiben, was und warum tun Sie, aber nicht, wie Sie es tun (zB "lassen Sie uns maximalen Wert in Preisen finden, werden wir es in Tabellenkopf anzeigen" ... aber nicht: "maximalen Wert in for-Schleife finden")

Answer 6

Steve McConnels Buch Code Complete - zweifellos das beste Buch zum Schreiben von Software - hat ein ganzes Kapitel darüber, wie man Kommentare schreibt und o stellen Sie sicher, dass Ihr Code verstanden wird - "selbst-dokumentierender Code" genannt.