Dokumentation: Unterschied zwischen den Versionen
Aus Das Sopra Wiki
Jeremi (Diskussion | Beiträge) |
Vogty (Diskussion | Beiträge) Keine Bearbeitungszusammenfassung |
||
| (5 dazwischenliegende Versionen von 5 Benutzern werden nicht angezeigt) | |||
| Zeile 63: | Zeile 63: | ||
</source> | </source> | ||
Es können auch eigene Token erstellt werden.<ref>http://msdn.microsoft.com/en-us/library/zce12xx2(VS.80).aspx Mircrosoft msdn Library - How to: Create Task List Comments</ref> | {{BA|Vogty|Tote Referenz auf Tokens und dazugehörigen Kommentar entfernt. <!--Es können auch eigene Token erstellt werden.<ref>http://msdn.microsoft.com/en-us/library/zce12xx2(VS.80).aspx Mircrosoft msdn Library - How to: Create Task List Comments</ref>-->}} | ||
==== Doxygen Befehle ==== | ==== Doxygen Befehle ==== | ||
Wird ein Programm wie [http://www. | Wird ein Programm wie [http://www.doxygen.nl/ Doxygen] verwendet, um aus dem Source Code automatisiert eine Dokumentation zu generieren, so können in den Kommentaren noch zusätzlich [http://www.doxygen.nl/manual/commands.html Special Commands] verwendet werden. Mit ihnen lassen sich zum Beispiel der Text formatieren oder man kann bestimmte Meta-Informationen zum Code mitgeben. | ||
[[Kategorie:Code-Beispiele]] | |||
=== Wie kommentieren? === | === Wie kommentieren? === | ||
==== Innerhalb von Methoden ==== | ==== Innerhalb von Methoden ==== | ||
Nach den [[CleanCode|Clean Code Prinzip]] sollte ein Programm sich selbst beschreiben und mit möglichst wenigen Kommentaren auskommen<ref>http://www.clean-code-developer.de/Source-Code-Konventionen.ashx Clean Code Developer - Source Code Konventionen</ref> | Nach den [[CleanCode|Clean Code Prinzip]] sollte ein Programm sich selbst beschreiben und mit möglichst wenigen Kommentaren auskommen:{{BA|Vogty|Tote Referenz entfernt. <!--<ref>http://www.clean-code-developer.de/Source-Code-Konventionen.ashx Clean Code Developer - Source Code Konventionen</ref>-->}} | ||
Statt: | Statt: | ||
| Zeile 96: | Zeile 96: | ||
==== Klassen bzw. außerhalb von Methoden ==== | ==== Klassen bzw. außerhalb von Methoden ==== | ||
Klassen Methoden, Prozeduren, Funktionen, etc. sollten mit [[Dokumentation#XML_Kommentare|XML Kommentaren]] versehen werden. Diese werden verwendet um die automatisierte Dokumentation zu bauen. | Klassen, Methoden, Prozeduren, Funktionen, etc. sollten mit [[Dokumentation#XML_Kommentare|XML Kommentaren]] versehen werden. Diese werden verwendet um die automatisierte Dokumentation zu bauen. | ||
Außerdem werden XML Kommentare dazu verwendet, bei der Codeeingabe Hinweise in einer Tooltip Box anzuzeigen, so dass das arbeiten mit dokumentierten Funktionen deutlich leichter fällt. [[Kategorie:Code-Beispiele]] | Außerdem werden XML Kommentare dazu verwendet, bei der Codeeingabe Hinweise in einer Tooltip Box anzuzeigen, so dass das arbeiten mit dokumentierten Funktionen deutlich leichter fällt. [[Kategorie:Code-Beispiele]] | ||
{{BA|Jeremi|Hier auf Parameter der XML Kommentare eingehen? So kommt sicher die Frage, ob nun ein Parameter, der in der summary beschrieben wurde jetzt auch nochmal einzeln beschrieben werden muss -> ja!}} | {{BA|Jeremi|Hier auf Parameter der XML Kommentare eingehen? So kommt sicher die Frage, ob nun ein Parameter, der in der summary beschrieben wurde jetzt auch nochmal einzeln beschrieben werden muss -> ja!}} | ||
=== Wie man NICHT kommentieren sollte === | === Wie man NICHT kommentieren sollte === | ||
| Zeile 121: | Zeile 120: | ||
Lösche nicht mehr gebrauchten Code, anstatt ihn auszukommentieren. Ansonsten sammeln sich nach und nach im Quellcode immer mehr Codeleichen an, die völlig unnötig sind. | Lösche nicht mehr gebrauchten Code, anstatt ihn auszukommentieren. Ansonsten sammeln sich nach und nach im Quellcode immer mehr Codeleichen an, die völlig unnötig sind. | ||
{{BA|Jeremi|Natürlich ist das nicht super streng gemeint. Beim Testen kann durchaus Code auskommentiert werden. Spätestens beim Commit ins | {{BA|Jeremi|Natürlich ist das nicht super streng gemeint. Beim Testen kann durchaus Code auskommentiert werden. Spätestens beim Commit ins Git sollte das aber raus}} | ||
==== Du sollst nicht Fluchen ==== | ==== Du sollst nicht Fluchen ==== | ||
| Zeile 130: | Zeile 129: | ||
Kommentieren ist schön und gut, aber wann genau soll nun kommentiert werden? Es gibt mehrere Ansätze, Kommentare zu verfassen, die auch von dem jeweiligen Programmierstil abhängen. | Kommentieren ist schön und gut, aber wann genau soll nun kommentiert werden? Es gibt mehrere Ansätze, Kommentare zu verfassen, die auch von dem jeweiligen Programmierstil abhängen. | ||
Bei einem geplanten Vorgehen überlegt man sich im Voraus, was der Code genau leisten soll. Dann spezifiziert man die Parameter und die Rückgabe und verfasst noch vor dem Implementieren einen Kommentar der beschreibt, was der Code leisten wird. Vorteil dieses Ansatzes ist, dass auf diese Weise Funktionen und Klassen markiert werden können, die man (oder ein anderer Entwickler) erst später implementieren wird. Solche Codestellen sollten unbedingt mit einem [[Dokumentation#Aufgabenliste-Kommentare| | Bei einem geplanten Vorgehen überlegt man sich im Voraus, was der Code genau leisten soll. Dann spezifiziert man die Parameter und die Rückgabe und verfasst noch vor dem Implementieren einen Kommentar der beschreibt, was der Code leisten wird. Vorteil dieses Ansatzes ist, dass auf diese Weise Funktionen und Klassen markiert werden können, die man (oder ein anderer Entwickler) erst später implementieren wird. Solche Codestellen sollten unbedingt mit einem [[Dokumentation#Aufgabenliste-Kommentare|Aufgabenliste-Kommentar]] markiert werden. | ||
Geht man etwas ungeplanter vor, so kann es passieren, dass man eine Funktion implementiert, diese aber kurze Zeit später erweitert, überarbeitet oder gar durch eine neue ersetzt. Jetzt jederzeit Kommentare zu schreiben, die man nur wenige Minuten später wieder wegschmeißt ist unnötiger Aufwand. Aus diesem Grund schiebt man das Kommentieren und somit das Dokumentieren der Funktion vor sich her. Dennoch sollte die finale Version der Funktion letztendlich kommentiert sein. | Geht man etwas ungeplanter vor, so kann es passieren, dass man eine Funktion implementiert, diese aber kurze Zeit später erweitert, überarbeitet oder gar durch eine neue ersetzt. Jetzt jederzeit Kommentare zu schreiben, die man nur wenige Minuten später wieder wegschmeißt ist unnötiger Aufwand. Aus diesem Grund schiebt man das Kommentieren und somit das Dokumentieren der Funktion vor sich her. Dennoch sollte die finale Version der Funktion letztendlich kommentiert sein. | ||
Ein guter Richtwert ist: ''Wenn man ins | Ein guter Richtwert ist: ''Wenn man ins Git committet, dann sollte alles kommentiert sein!'' (Committen sollte man sowieso nur sauberen Code.) | ||
<noinclude>== Referenzen == | <noinclude>== Referenzen == | ||
