Dokumentation: Unterschied zwischen den Versionen
Aus Das Sopra Wiki
Max (Diskussion | Beiträge) |
Vogty (Diskussion | Beiträge) Keine Bearbeitungszusammenfassung |
||
| (3 dazwischenliegende Versionen von 3 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 120: | 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 133: | Zeile 133: | ||
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 == | ||
