Hi @ all, ich hab da eine Frage. Ich bin fleißig am Programmieren setze auch schön Kommentare wie es sich gehört. Meine Frag jetzt eigentlich ist wie werden Funktionen Richtig kommentiert bzw. Beschrieben ich hab das Vergessen. Auf die Schnelle finde ich nichts im Internet wahrscheinlich weil ich die Falschen Schlagwörter verwende. Ich weiß da gehört sowas wie Rückgabetyp rein was die Funktion macht aber halt nicht mehr genau was alles. Kann mir jemand freundlicher weise eine link schicken oder so weiter helfen. Ich danke schon mal jetzt für eure Unterstützung. mfg m.s.
doxygen ist recht verbreitet und auch praktisch
Gast
#2283073
Du kannst diese Kästen mit * und - machen, oder du schaust nach einem Tool, das mit deinen Angaben eine hübsche Doku machen kann. Dann musst du den Syntax von diesem Tool nehmen. Wie Vlad schon schrieb, ist doxygen eine Möglichkeit.
Wichtig bei Kommentaren: Beschreibe nicht, was du machst, das sagt der Quellcode. (Ausnahme: Ein besonders ausgefuchster Algorithmus evtl.) Beschreibe statt dessen, warum du etwas machst und in was für einem Zusammenhang es steht. Das sind die Dinge, die du dir nur denkst, die aber nicht im Quellcode zu sehen sind.
Jo danke für eure Hilfe. mfg m.s.
Edit:
1 | |
Ein unnützter Kommentar wäre: "Die Funktion gibt einen Integer zurück." Sinnvoll hingegen: "Die Funktion ist eine Hilfsfunktion, die die aktuelle Uhrzeit vom Zeitpunk des Programmstarts abzieht. Rückgabewert: Die Differenz in Millisekunden." Edit2: Der Funktionsname ist auch schon denkbar ungeeignet ;-)
Sven H. schrieb: > Der Funktionsname ist auch schon denkbar ungeeignet Wenn noch Funktionen wie machWas, lassWas und machNix dazukommen, wird das Namensquartett vollständig ...
Moin, für Doxygen habe ich mir diese Kommentar Einstellungen zusammen gefriemelt, falls interesse:
1 | |
2 | |
3 | |
4 | |
5 | |
6 | |
7 | |
8 | |
9 | |
10 | |
11 | |
12 | |
13 | |
14 | |
15 | |
Gruß
Jean Player schrieb: > <B>Function Name</B> : UsbReceive <BR><B>Description</B> : when data is received in function das ist ziemlich Sinnfrei, weil das Doxygen schom mitgeneriert und im Code direkt drunter steht. die doppelpunkte sind auch ziemlich sinnlos, die stehen nachher am anfang des generierten Abschnitts folgendes: Jean Player schrieb: > @param Input : received data and the length of data > for the ring puffer > @param Output : None > @param Return : None produziert sogar jede menge Doxygen fehler. Das ganze Beispiel ist ein gutes Beispiel dafür, wie man Doxygen nicht benutzt
Gast
#2283185
Zuerst mal, warum schreibt man nicht USB-Receive statt UsbReceive ? Nur um der Konvention GroßbuchstabeZuAnfang zwanghaft zu folgen? Dann, warum muss man sich dem Schema einer Dokumantationssoftware fügen? Eine Beschreibung wie man sie anderen "erzählen" würde klingt doch irgendwie eingängiger: Der Funktion UsbReceive() wird ein Zeiger auf ein Datenfeld übergeben und die Datenfeldgröße. Der Rückgabewert ist void. Sie ruft ihrerseits die Funktion EP3_OUT_Callback() auf. Wegen mir kann man auch noch den Zeigertyp und die den Datentyp für die Feldgröße dazuschreiben, z.B. Der Funktion UsbReceive() wird ein Zeiger auf ein Datenfeld vom Typ uint8_t übergeben und die Datenfeldgröße vom Typ uint16_t. Der Rückgabewert ist void. Sie ruft ihrerseits die Funktion EP3_OUT_Callback() auf.
Vlad Tepesch schrieb: > Das ganze Beispiel ist ein gutes Beispiel dafür, wie man Doxygen nicht > benutzt sondern?
die Bescreibung selbst sit auch extrem sinnfrei. Es bringt nix hinzuschreiben, von wo eine Funktion gecallt wird (das findet Doxygen auch alleine durch Codeanalyse heraus). Man sollte schreiben, wozu die Funktion gut, wie sie es erledigt und eventuell wie aufwendig sie ist. ein schöneres Beispiel aus dem Quellcode (den saubereren Teilen) der Word Clock:
1 | |
2 | |
3 | |
4 | |
5 | |
6 | |
7 | |
8 | |
9 | |
10 | |
11 | |
oder
1 | |
2 | |
3 | |
4 | |
5 | |
6 | |
7 | |
8 | |
9 | |
10 | |
11 | |
12 | |
Olaf schrieb: > Zuerst mal, warum schreibt man nicht USB-Receive statt UsbReceive ? Konvention, Style-Guide, Bindestrich nicht erlaubt (bzw. theoretisch erlaubt, Quelltext aber nur ASCII d.h. Bindestrich = Minus), was ist wenn z.B. lokale Variablen mit einer Abkürzung anfangen z.B. uSBIrgendwas, dann ist es einfacher (und sieht besser aus) auch Abkürzungen generell mit Kleinbuchstaben zu schreiben: usbIrgendwas > Dann, warum muss man sich dem Schema einer Dokumantationssoftware fügen? > > Eine Beschreibung wie man sie anderen "erzählen" würde klingt doch > irgendwie eingängiger: > > > Der Funktion UsbReceive() wird ein Zeiger auf ein Datenfeld übergeben > und die Datenfeldgröße. Der Rückgabewert ist void. Sie ruft ihrerseits > die Funktion EP3_OUT_Callback() auf. Das ist redundant Die Typen stehen da schon, der Aufruf ist auch ersichtlich > Der Funktion UsbReceive() wird ein Zeiger auf ein Datenfeld vom Typ > uint8_t übergeben und die Datenfeldgröße vom Typ uint16_t. Auch überflüssig, wenn die Parameternamen selbstsprechend sind
Olaf schrieb: > Dann, warum muss man sich dem Schema einer Dokumantationssoftware fügen? weil man dann daraus ganz einfach ansprechende, übersichtliche Dokumentationen für Bibliotheken erzeugen kann > > Eine Beschreibung wie man sie anderen "erzählen" würde klingt doch > irgendwie eingängiger: nicht wirklich. einer stichpunktartigen Auflistung, die immer nach dem gleichen Schema aufgebaut wird, kann man viel schneller Informationen entnehmen, als wenn man erst sätzeweise Prosa durchforsten muss. und Funktionen von anderen beschrieben zu bekommen bringt meiner Meinung nach, auch nicht wirklich viel. Wenn das nötig ist, um den Code zu verstehen, ist dieser schlecht geschrieben oder nicht aussagekräftig genug dokumentiert.
Gast
#2283462
Arc Net (arc) schrieb: Olaf schrieb: >> Der Funktion UsbReceive() wird ein Zeiger auf ein Datenfeld übergeben >> und die Datenfeldgröße. Der Rückgabewert ist void. Sie ruft ihrerseits >> die Funktion EP3_OUT_Callback() auf. > Das ist redundant > Die Typen stehen da schon, der Aufruf ist auch ersichtlich >> Der Funktion UsbReceive() wird ein Zeiger auf ein Datenfeld vom Typ >> uint8_t übergeben und die Datenfeldgröße vom Typ uint16_t. > Auch überflüssig, wenn die Parameternamen selbstsprechend sind Redundant != überflüssig oder betrachtest du redundante Sicherheitssystem als "überflüssig"? Zu erst einmal, worüber sprechen wir hier eigentlich? Über eine Dokumentation für den Arbeitgeber oder andere "Fremde Leute" oder sprechen wir hier über die Dokumentation die einem selber dient, um sich im eigenen Programm bei Gelegenheit wieder zurechtzufinden? Das ist nämlich nicht das gleiche. Für mich liest sich so eine "humanoid gestaltete" Beschreibung wie im Beispiel von mir wesentlich eingängiger, als eine Abstrakte Schnittstellenbeschreibung. Ich würde vielleicht noch dazuschreiben was die Funktion genau macht. Mir gehen diese Texte auf den Keks, die selber eher komplizierter sind als ein Blick in den Quelltext, sowas möchte ich nicht haben. Gib also mal ein Beispiel an wie DU es besser machen würdest, anstatt einfach nur zu schreiben "ist redundant, also überflüssig". Und bedenke auch mal, dass viele Fehler gerade im Umgang mit Zeigern geschehen, deshalb habe ich eine verbale Formulierung wie oben gerne beleitend mit drin. Es ist nicht jeder ein SW-Crack wie du es vielleicht bist.
Gast
#2283465
Vlad Tepesch (vlad_tepesch) schrieb: >> Eine Beschreibung wie man sie anderen "erzählen" würde klingt doch >> irgendwie eingängiger: > nicht wirklich. > einer stichpunktartigen Auflistung, die immer nach dem gleichen Schema > aufgebaut wird, kann man viel schneller Informationen entnehmen, als > wenn man erst sätzeweise Prosa durchforsten muss. Das will ich erst mal sehen. Gib mal dein Beispiel an.
Olaf schrieb: > Redundant != überflüssig oder betrachtest du redundante > Sicherheitssystem als "überflüssig"? Was hat das ganze mit Sicherheit zu tun? redundante Information == überflüssige Information irgendwann passiert es zwangsläufig, dass man vergisst eins mitzuändern und schon sind die Infos nicht mehr redundant, sondern widersprüchlich. Olaf schrieb: > Das will ich erst mal sehen. Gib mal dein Beispiel an. bist du blind? Ein besipiel habe ich doch gepostet? warum soll ich im Text (wo ich es erst suchen müsste) schreiben, dass der Rückgabewert void ist, wenn genau dass eine Zeile drunter in der Deklaration bereits steht? selbiges gilt für die Typen der Argumente. da ist es nicht wichtig zu schreiben, was für ein Typ ist es - das steht bereits da, sondern was bewirkt das Argument und eventuell Metainformationen zum Argument, die die Sprache nicht direkt unterstützen, wie zB eingeschränkte Wertebereiche, Umrechnungsfaktoren,
Gast
#2283519
Vlad Tepesch schrieb: > und Funktionen von anderen beschrieben zu bekommen bringt meiner Meinung > nach, auch nicht wirklich viel. > Wenn das nötig ist, um den Code zu verstehen, ist dieser schlecht > geschrieben oder nicht aussagekräftig genug dokumentiert. Das ist der groesste Unsinn, der je verbreitet wurde und kostet jedes Jahr Milliarden. Es waere schon, wenn Leute die sowas glauben nie ein Handbuch gelesen haetten, denn dann wuerden sie ueberhaupt keine Programme schreiben koennen und die Welt mit ihrem Mist verschonen. In Wirklich dient diese "Philosophie" aber nur eine faule Ausrede selbstverliebter Hacker - eigener Code ist stets Prosa und muss nicht dokumentiert werden, fremder Code ist prinzipiell einfach nur Muell, sonst wuerde man ihn ja ohne Dokumentation verstehen. Es gibt genau 2 Situationen, bei denen ich mit fremdem Code in Kontakt komme: 1) Wenn ich ihn benutze. Dann muss ich auf keinen Fall in den Code gucken, da ich lediglich mit der Schnittstellenbeschreibung arbeite und mich auch nur darauf verlassen darf, was die Funktion eventuell sonst noch tut. 2) Wenn ich ihn warte - dann ist die Dokumentation die Referenz und niemals der Code. Das Wort "selbsterklaerend" gehoert in der Informatik verboten - selbst einfachste Funktionen sind das nicht. Wer das glaubt, hat schlicht nicht genug Erfahrung. Schon triviale Funktionen stecken voller Randbedingungen, die dokumentiert werden muessen. Oft ist sogar viel wichtiger, was eine Funktion nicht kann oder wann sie nicht funktioniert, als die Beschreibung ihres Hauptzwecks. Leider ist es so, dass sich in der Informatik selbst die groessten Gruenschnaebel fuer grossartige Hacker halten. Ich weiss nicht woran es liegt, aber wohl nirgends sonst ist der Gottkomplex so verbreitet. Und so wird wild drauflos gehackt, ja nicht auf andere gehoert oder Ruecksicht genommen. Das Forum hier ist das beste Beispiel dafuer.
Peter Stegemann schrieb: > 2) Wenn ich ihn warte - dann ist die Dokumentation die Referenz und > niemals der Code. Noch nie über Code gestolpert, desse exzellente Dokumentation dem realen Code ein paar Jahre hinterher hinkte (Betonung auf "hinkte")? > Leider ist es so, dass sich in der Informatik selbst die groessten > Gruenschnaebel fuer grossartige Hacker halten. Ich weiss nicht woran es > liegt, aber wohl nirgends sonst ist der Gottkomplex so verbreitet. Auf die Idee, einen kilometergrossen Beschleunigerring in den Boden zu buddeln kommt man ausserhalb finanzkräftiger Institute nicht so schnell. In solchen Bereichen kommt für Normalmenschen einfach nichts bei raus. Fürs Programmieren braucht man jedoch nur einen einfachen Computer. Und irgendwann kommt sogar was dabei raus, was von Aussen nicht sofort nach Müll aussieht. Also kann da jeder ran. Und mokiert sich anschliessend lautstark im Forum drüber, dass das doch nun wirklich jeder könne, wozu also Informatik. ;-)
Gast
#2283550
Vlad Tepesch (vlad_tepesch) schrieb: > bist du blind? > Ein besipiel habe ich doch gepostet? Naja, ehrlich gesagt mit deiner Doku (deinem Beispiel) kann ich auch nicht viel anfangen. So würde ich nicht kommentieren. Ich hab übrigens Redundanz ganz gerne. Liegt wohl daran, dass ich mir Sätze auch gerne zwei mal oder mehrfach durchlese bis der Groschen gefallen ist. Ihr mit euerm IQ > 150 braucht das wohl nicht. ;) @ Peter Stegemann (pst) Was du schreibst klingt für mich schon viel nachvollziehbarer.
Gast
#2283608
Mahlzeit, mal ein paar Bemerkungen zu obigen Beiträgen/verwendeten Begriffen: "selbsterklärend": Natürlich sollte ein Programmtext selbsterklärend sein! Wer ein Programm nicht versteht, sollte erst mal einen Informatikkurs besuchen bzw. sich ein entsprechendes Buch o.ä. besorgen. Und ist ein Stück Quelltext auf den ersten Blick nicht selbserklärend, weil Ideeblitz kurz vor dem Einschlafen und man vergißt ja auch mit der Zeit wieder etwas, dann kommentiert man genau diese Stelle. "nur die Dokumentation ist relevant und lese ich...": Ja klar hoffentlich hat derjenige auch wirklich alles vollständig und fehlerfrei beschrieben... --> Programmierer sind zwar Götter, aber auch nur Menschen! Wenn der Code nicht das macht, was in der Beschreibung steht, dann wirfst du ihn wieder raus? Nicht schlecht, hoffentlich machst du das nicht so oft, denn das kostet auch ein paar Millarden (global gesehen...). (wiederverwendbare) "Schnittstellenbeschreibung": Da gebe ich recht, da sollte eine vorhandene Beschreibung schon das widerspiegeln, was die Funktion macht und wie sie einzusetzen ist. Am Besten macht man das, meiner Meinung, auch über ein kommentiertes Beispiel! "Wartung": Wann spricht man von Code-Wartung? Dann wenn ein Fehler auftritt. (Dann stimmt auch die eventuell vorhandene Beschreibung nicht!) Wenn eine Funktion erweitert/geändert werden soll. In beiden Fällen sollte man dann den (hoffentlich selbsterklärenden)Programmtext verstehen oder die Finger von lassen und den ursprünglichen Autor kontaktieren! Grüße von einem, der seit 25 Jahren Gottkomplexe hat...
Gast
#2283615
A. K. schrieb: > Peter Stegemann schrieb: >> 2) Wenn ich ihn warte - dann ist die Dokumentation die Referenz und >> niemals der Code. > Noch nie über Code gestolpert, desse exzellente Dokumentation dem realen > Code ein paar Jahre hinterher hinkte (Betonung auf "hinkte")? Doch. Und warum? Weil die 2 Regeln ignoriert wurden. > Also kann da jeder ran. Und mokiert sich anschliessend lautstark im > Forum drüber, dass das doch nun wirklich jeder könne, wozu also > Informatik. ;-) Ich habe leider feststellen muessen, dass auch ein Studium oder eine Lehre bei dem Problem nicht hilft. Auch viel Jahre Praxis hilft leider bei vielen Entwicklern nicht. Vieleicht liegt es daran, dass man in der Branche zu selten auf die eigenen Hinterlassenschaften stoesst.
Gast
#2283616
Sowas:
1 | |
2 | |
gibt 'nen Anschiss vom Scheff... So hingegen überlebts den Codereview:
1 | |
2 | |
Peter Stegemann schrieb: >[...] kann es sein, dass du mich falsch verstanden hast? Ich habe von code erklären geredet, nicht code dokumentieren. Die Aussage war, dass es besser ist, Code so zu dokumentieren, wie man ihn erklären würde: in Prosa. die Deklaration einer Schnittstelle in Prosa zu wiederholen ist in jedem Fall sinnlos. > Es gibt genau 2 Situationen, bei denen ich mit fremdem Code in Kontakt > komme: > > 1) Wenn ich ihn benutze. Dann muss ich auf keinen Fall in den Code > gucken, da ich lediglich mit der Schnittstellenbeschreibung arbeite und > mich auch nur darauf verlassen darf, was die Funktion eventuell sonst > noch tut. > > 2) Wenn ich ihn warte - dann ist die Dokumentation die Referenz und > niemals der Code. genau das ist das Ziel einer Dokumentation. wenn du darauf angewiesen bist, dass dir zusätzlich zu dieser Dokumentation noch jemand den Code erklärt, dass ist der Code oder die Dokumentation schlecht. > > Das Wort "selbsterklaerend" gehoert in der Informatik verboten - selbst > einfachste Funktionen sind das nicht. Code sollte selbst sprechen. in vielen Fällen könnte man Kommentare vermeiden, wenn man den Code besser schreibt: Beispiel: Gut:
1 | |
2 | |
3 | |
4 | |
besser:
1 | |
2 | |
> Wer das glaubt, hat schlicht nicht genug Erfahrung. wie obiges Beispiel zeigt, könnte aber auch der umgekehrte Fall gelten. > Schon triviale Funktionen stecken voller Randbedingungen, > die dokumentiert werden muessen. Randbedingungen müssen natürlich dokumentiert werden. > Oft ist sogar viel > wichtiger, was eine Funktion nicht kann oder wann sie nicht > funktioniert, als die Beschreibung ihres Hauptzwecks. sicher, das und die Randbedingungen gehören zur Schnittstellendokumentation der Funktion, nicht in die eigentlichen Code-Kommentare
Olaf schrieb: > Vlad Tepesch (vlad_tepesch) schrieb: > >> bist du blind? >> Ein besipiel habe ich doch gepostet? > > Naja, ehrlich gesagt mit deiner Doku (deinem Beispiel) kann ich auch > nicht viel anfangen. So würde ich nicht kommentieren. was gefält dir denn daran weniger gut als: "Die funktion pwm_lock_brightness_val ist als extern definiert, bekommt ein uint8_t als Eingangsparameter und hat keinen Rückgabewert" ? Es werden in einer definierten Art und Weise eine Kurzbeschreibung für Übersichten, eine Langbeschreibung mit (gewollten) Seiteneffekten, zur verwendung, sowie detailierte Informationen zu den Parametern gegeben > > Ich hab übrigens Redundanz ganz gerne. Liegt wohl daran, dass ich mir > Sätze auch gerne zwei mal oder mehrfach durchlese bis der Groschen > gefallen ist. > Ihr mit euerm IQ > 150 braucht das wohl nicht. ;) genau das ist doch der Punkt: warum sollte ich Sätze lesen wollen, deren Verschachtelung und Struktur der in mir integrierte Syntaxparser erst zerlegen muss (und die ich dafür, je nach Autor, auch mal mehrmals lesen muss), wenn ich stattdessen auf eine klar und immer ähnlich aufgebaute Struktur schauen kann und sofort weiß, da steht die Information, die ich gerade benötige. Angenommen, ich weiß, wie die Funktion heißt und was sich macht, will nur noch wissen, wie die Inputs formatiert sind. Dann schau ich auf den Kommentar, sehe die @input tags, und lese die Beschreibung. Anderernfalls gehe ich zum Kommentar, lese erstmal mindestens (bei vernünftiger Dokumentation) 7-10 Zeilen Prosa in denen die Info eingeflochten ist. Kleines Beispiel schrieb: > Sowas: > int zwerg; > int dwarf; > gibt 'nen Anschiss vom Scheff... > > So hingegen überlebts den Codereview: > int zwerg; // ZWischenERGebnis > int dwarf; // Data With(out) A Reasonable Function Also so ein Englisch-Deutsch-Mischmasch würde bei uns kein Codereview überleben
Gast
#2283747
> die Deklaration einer Schnittstelle in Prosa zu wiederholen ist in jedem > Fall sinnlos. Prosa liest sich aber viel schöner :) und ist vor allem auf Anhieb fehlerfreier als dein Doxygen wie du selber festgestellt hast "produziert sogar jede menge Doxygen fehler. Das ganze Beispiel ist ein gutes Beispiel dafür, wie man Doxygen nicht benutzt" Ist also ein Tool das selber wieder anfällig für (neue) Fehler ist. Dann lieber ein bisschen Prosa samt Erläuterung (die ich weglies; hatte ja auch keine Info darüber). Ist eh nur für mich. Aber ihr stilisiert ja gerne jeden noch so unbedeutenden Akt zum Weltereignis hoch. By the way, ist eigentlich die hungary notation schon out? MS hat die doch gerne verwendet und hier in meinem Büchlein steht se auch noch drin. > So hingegen überlebts den Codereview: > int zwerg; // ZWischenERGebnis > int dwarf; // Data With(out) A Reasonable Function ist auch nicht besser als vorher Zwischenergebnis int i_tmp, j_tmp, tmp_data, tmp_value; sonstiges Datum irgend einen Sinn wird dein Datum schon haben, also benenne es doch nach diesem (Sinn) bFlagPleite Kto_stand nTage_bis_Raeumung percentVal
Vlad Tepesch schrieb: > Jean Player schrieb: >> <B>Function Name</B> : UsbReceive > <BR><B>Description</B> : when data is received in function > > das ist ziemlich Sinnfrei, weil das Doxygen schom mitgeneriert und im > Code direkt drunter steht. Naja das mag jeder sehen wie er will. > die doppelpunkte sind auch ziemlich sinnlos, die stehen nachher am > anfang des generierten Abschnitts Nö, das ist Schwachsinn! Siehe meinem Anhang. > Jean Player schrieb: >> @param Input : received data and the length of data >> for the ring puffer >> @param Output : None >> @param Return : None > produziert sogar jede menge Doxygen fehler. > Das ganze Beispiel ist ein gutes Beispiel dafür, wie man Doxygen nicht > benutzt Auch das ist Schwachsinn, lerne erstmal Doxygen zu bedienen. Ansonsten würde wohl kaum mein Anhang generiert werden. Zudem siehst du , das ein Link automatisch zu der Datei usb_endp.c erzeugt wird , von der Sie aufgerufen wird, also sinnvoll, das einzutragen. Meine Meinung zumindest. Gruß
Angehängte Dateien:
-
Untitled.png
(20 KB)
Olaf schrieb: > Ist also ein Tool das selber wieder anfällig für (neue) Fehler ist. Im Gegenteil: Es sagt dir, wenn deine Dokumentation fehler enthält, wie zB die dokumentation eines Rückgabewertes, wo keiner ist. Oder die fehleden Dokumentation eines Parameters. In Java erzeugt sowas sogar standardmäßig Warnungen, ohne Zusatztools > By the way, > ist eigentlich die hungary notation schon out? MS hat die doch gerne > verwendet und hier in meinem Büchlein steht se auch noch drin. Ja sie ist out. Ich hab mal gelesen oder gehört, dass sie nie so gemeint war, wie sie umgesetzt wurde. den Typ einer Variable vorranzustellen ist sinnlos. Bei einer Typänderung muss alles umbenannt werden. Außerdem zeigt jede moderne IDE die Deklaration an, wenn man über eine Variable geht. Sinn machen Präfixes dennoch. zB um bei Funktionen read only, write only und read/write Parameter zu kennzeichnen (i_ o_ io_) Das kann nämlich auch keine IDE. oder auch um auf Besonderheiten hinzuweisen, wie einen besonderen Scope, wie global, oder statische (g_ s_ gs_). Aber das ist Geschmackssache. Olaf schrieb: > bFlagPleite > Kto_stand > nTage_bis_Raeumung > percentVal die Verwendung deskriptiver Variablennamen ist doch schon ein guter Schritt - das spart auch Kommentare Ich würde aber konsequent auf lower camel case setzen und Unterstriche nur in Makros und zur Abtrennung von Prefixes zu verwenden
Microsoft als Vorbild für Programmierkonventionen zu verwenden ist ohnhin etwas mutig. Denen haben wird immerhin zu verdanken, dass auch 64-Bit Prozessoren eine Wortbreite von 16 Bits haben und man dank dieser ungarischen Notation in fast jeder einzelnen verdammten Quellcodezeile an jene uralten Zeiten erinnert wird, in denen das mal stimmte.
Jean Player schrieb: >> das ist ziemlich Sinnfrei, weil das Doxygen schom mitgeneriert und im >> Code direkt drunter steht. > > Naja das mag jeder sehen wie er will. Jean Player schrieb: >> die doppelpunkte sind auch ziemlich sinnlos, die stehen nachher am >> anfang des generierten Abschnitts > > Nö, das ist Schwachsinn! Siehe meinem Anhang. ja ok, vor deinen Doppelpunkten steht text. würdest du schreiben @details : sasdsad würden die Doppelpunkte am Anfang des Absatzes stehen Jean Player schrieb: >> produziert sogar jede menge Doxygen fehler. >> Das ganze Beispiel ist ein gutes Beispiel dafür, wie man Doxygen nicht >> benutzt > > Auch das ist Schwachsinn, lerne erstmal Doxygen zu bedienen. > Ansonsten würde wohl kaum mein Anhang generiert werden. Dann schau dir mal die Meldungen an, den Doxygen produziert. Da wird etwas stehehn, wie (den genauen Wortlaut kenne ich nicht) Warning function UsbReceive does not have parameter Input Warning function UsbReceive does not have parameter Output Warning function UsbReceive does not have parameter Return Warning No documentation for parameter data in function UsbReceive found Warning No documentation for parameter size in function UsbReceive found Doxygen ist was Warnungen angeht leider zu tolerant und erzeugt trotzdem jede menge Output. Jean Player schrieb: > Zudem siehst du , das ein Link automatisch zu der Datei usb_endp.c > erzeugt wird , von der Sie aufgerufen wird, also sinnvoll, das > einzutragen. > Meine Meinung zumindest. wenn du im "Caller Graph" schauen würdest, würdest du sofort sehen, wer die Funktion aufruft, kannst draufklicken und die auch die Sourcen anschauen, insofern in die Dokumentation inkludiert. und das ganz ohne jeden Aufruf jeder Funtkion in jedem Kommenar von Hand nachzupflegen. Das funktioniert auf Dauer nämlich nicht - und erst recht nicht in größeren SW-Projekten und erst recht nicht, wenn mehr als einer daran arbeitet.
A. K. schrieb: > Microsoft als Vorbild für Programmierkonventionen zu verwenden ist > ohnhin etwas mutig. Denen haben wird immerhin zu verdanken, dass auch > 64-Bit Prozessoren eine Wortbreite von 16 Bits haben und man dank dieser > ungarischen Notation in fast jeder einzelnen verdammten Quellcodezeile > an jene uralten Zeiten erinnert wird, in denen das mal stimmte. das ist ja eher der Abwärtskompatibilität der WinAPI geschuldet
Man hab ich mit meiner Frage ne diskusion breitgetreten ist aber echt interesant. mfg m.s.
Gast
#2283795
> Funktionen in C richtig Komentieren Mit 2 m > Meine Frag jetzt eigentlich ist wie > werden Funktionen Richtig kommentiert Im Prinzip: Gar nicht. Wenn es dir nicht gelingt, in C verständlichen Code zu schreiben, wirst du auch keinen verständlichen Kommentar dazu verfassen können. Wenn du jedoch beim Schreiben der Funktion schon bemerkst, daß es ein merkwürdiges unverständliches Verhlaten hat, welches später mal zu Problemen führen könnte, DANN solltest du dazu einen Kommentar schreiben. Das sollte bei einem guten Programm aber eher selten der Fall sein. Merke: Was im Kommentar steht, ist meinstens doppelt gemoppelt, es steht doch viel genauer schon im Code dadrunter. Und meistens ist es dann auch noch flasch, denn 2 Sätze sagen selten dasselbe aus. Manchmal kann es nützlich sein, Dinge graphisch aufzuschreiben "ein Bild sagt mehr als 1000 Worte" doch dazu hilft dir die Koomentarfunktion selten weil in ACSII eben schlecht zu zeichnen ist.
Vlad Tepesch schrieb: > das ist ja eher der Abwärtskompatibilität der WinAPI geschuldet Eben. Benenne die Dinger nach der Funktion, nicht nach der Grösse. Die Funktion bleibt, die Grösse aber oft nicht. Wenn jede Variable die Grösse mitschleppt, dann musst du queerbeet durch den ganzen Code sämtliche Variablen umbenennen, die einfach bloss die natürliche Wortgrösse der Maschine reflektieren, wenn du von n-Bit auf k-Bit Maschinen portierst. Was für ein Blödsinn. Sowas gehört in den Datentyp und nur dorthin. Dort kannst du per typedef solche Abhängigkeiten sauber an zentraler Stelle klären. Wenn du dann den typedef an dieser zentralen Stelle von dw auf qw vergrösserst und die ungarischen Variablen auf dw lässt, dann hast du verloren weil Verarsche, und wenn du sie umbenennst heisst du Sysiphos.
Gast
#2283814
Vlad Tepesch (vlad_tepesch) schrieb: .. hungary notation schon out? > Ja sie ist out. > Ich hab mal gelesen oder gehört, dass sie nie so gemeint war, wie sie > umgesetzt wurde. > den Typ einer Variable vorranzustellen ist sinnlos. > Bei einer Typänderung muss alles umbenannt werden. Na komm, letzteres ist doch mit jedem Editor in Windeseile erledigt. In älteren MS Fibeln findet man schon noch Ansätze der HN wie iLength, iTime, iDate, iCmdShow (aus Win32-Code) pText (p = pointer) Also ich deklariere einen - String noch immer gerne als: strHlp - ein Zeichen als chKeybrd oder cKeybrd Olaf schrieb: >> bFlagPleite >> Kto_stand >> nTage_bis_Raeumung >> percentVal > die Verwendung deskriptiver Variablennamen ist doch schon ein guter > Schritt - das spart auch Kommentare gefällt mir auch sehr gut ;) > Ich würde aber konsequent auf lower camel case setzen und Unterstriche > nur in Makros und zur Abtrennung von Prefixes zu verwenden gelingt mir nicht so streng das einzuhalten Zugegeben, bei der Kommentierung hadere ich oft genug noch mit mir. Huch .. jetzt ist Gewitter ; schluss vorerst ;)
@A.K. die Typen hätten sie aber auch nicht ändern können, da ja die Binärkompatibilität sonst nicht gewart wäre - unabhängig von der benennung
Olaf schrieb: > Na komm, letzteres ist doch mit jedem Editor in Windeseile erledigt. Keineswegs einfach, denn du änderst den zentral definierten Datentyp und musst dann zwecks Umbenennung in sämtlichen Quellcodefiles nach allen Variable dieses Typs suchen. Ausserdem macht dieses Verfahren es unmöglich, Code zu schreiben, der unabhängig von Wortbreiten einsetzbar ist. Statt dessen brauchst du diverse Versionen, die sich funktional überhaupt nicht unterscheiden, nur im Typ und im ungarischen Präfix. > Also ich deklariere einen > - String noch immer gerne als: strHlp > - ein Zeichen als chKeybrd oder cKeybrd Vertretbar ist es, Typen unterschiedlicher Funktion zu differenzieren. Also Integers, Booleans, Strings voneinander zu unterscheiden.
Olaf schrieb: > Vlad Tepesch (vlad_tepesch) schrieb: > > .. hungary notation schon out? Ja. Weil so, wie speziell MS das verbreitet hat, war das nie gedacht. Die Präfixe sollten in der Originalidee eine Funktionalität anzeigen und keinen Datentyp. Aus bereits genannten Gründen, ist die Datentypidee ziemlicher Schwachsinn. Oder wer behält schon den Überblick welches 2 Buchstabenkürzel jetzt für welche der 100 Strukturen/Klassen steht? Wenn du HN brauchst um deinen Code lesbar zu machen, dann machst du was falsch. Vernünftige Variablennamen bringen wesentlich mehr als dieses HN gedöns. Das einzige was bei mir aus der MS_HN Zeit übrig geblieben ist, ist das kleine p, mit dem der Name einer Pointervariablen anfängt. Ist im Grunde auch nicht wirklich notwendig, weil mir der Compiler schon sagt ob ich -> richtig anwende oder ob es nicht doch ein . sein müsste, aber es spart ein paar Compilerläufe ein, bis man es richtig hat. Code ist nie vollständig selbsterklärend, weil die Nebenbedingungen so nicht ersichtlich sind. Das ist aber kein Grund, dass man nicht danach streben sollte. So was: > int zwerg; > int dwarf; > gibt 'nen Anschiss vom Scheff... > > So hingegen überlebts den Codereview: > int zwerg; // ZWischenERGebnis > int dwarf; // Data With(out) A Reasonable Function ist einfach nur Unsinn. Wenn du neben eine Variable ein oder zwei Wörter brauchst um anzuzeigen, welchen Zweck diese Variable erfüllt, dann kannst du gleich einen andern Variablennamen wählen, der den Kommentar überflüssig macht. Das kommt dann automatisch auch allen verwendenden Stellen im Code zu gute. Das heißt nicht, dass Kommentare neben Deklarationen generell überflüssig sind. Aber da gehören Wertebereiche hin, Nebenbedingungen etc. Verwendet man in Variablennamen Abkürzungen, dann sollten die geläufig sein. Mwst ist in einer kaufmännischen Software sicherlich als Kürzel für Mehrwertsteuer zulässig. Drm als Kürzel Drehmoment wird hingegen Probleme machen, es sei dann das ganze Team ist auf dieses Kürzel geeicht. Meine Meinung zur Schnittstellenbeschreibung in Prosa: Ich halte es da mit Vlad. Eine Prosabeschreibung der Datentypen der Parameter bringt genau gar nichts. Im besten Fall sagt sie dasselbe aus, was ich auch im C-Funtionsheader lesen kann. Im schlimmsten Fall ist sie einfach nur falsch. Der Funktionsheader hat aber den entscheidenden Vorteil, dass sich der Compiler danach richtet. Die Prosabeschreibung hingegen ist ihm sowas von schnuppe. Das hier > "Die funktion pwm_lock_brightness_val ist als extern definiert, > bekommt ein uint8_t als Eingangsparameter und hat keinen Rückgabewert" erzählt mir nichts, was ich nicht auch durch Studium des Headerfiles bzw. der aus dem Code generierten Doku erfahren würde.
1 | |
Nur hat diese Zeile aus dem Header File den Vorteil, dass sie für den Compiler verbindlich ist. Aber ansonsten enthält sie genau dieselbe Information wie der Prosatext. Alte Datenbankweisheit: speichere dieselbe Information nie 2 mal ab. Denn irgendwann werden die beiden Informationen auseinanderlaufen, obwohl sie es nicht sollten.
Jean Player schrieb: > lerne erstmal Doxygen zu bedienen. > Ansonsten würde wohl kaum mein Anhang generiert werden. was ich dazu noch sagen wollte: Ich kann sehr wohl mit Doxygen umgehen. Ich habe schon recht umfangreiche Dokumentation damit erstellt. Sogar Fehler im Code gefunden und Fixes vorgeschlagen. Hier nochmal zum Nachlesen, wegen dem @param: http://www.stack.nl/~dimitri/doxygen/commands.html#cmdparam
Karl Heinz Buchegger schrieb: > Wenn du HN brauchst um deinen Code lesbar zu machen, dann machst du was > falsch. Vernünftige Variablennamen bringen wesentlich mehr als dieses HN > gedöns. Das einzige was bei mir aus der MS_HN Zeit übrig geblieben ist, > ist das kleine p, mit dem der Name einer Pointervariablen anfängt. Stimmt nicht ganz, wenn ich es recht bedenke. Einige wissen, dass ich im Bereich CAD unterwegs bin. Und da gibt es normalerweise mehere Koordinatensyteme: da ist zum einen das lokale Koordinatensystem des jeweiligen Objektes, das absolute Koordinatensystem und noch diverse andere Koordinatensysteme je nach Arbeitsebenen etc. Nach vielen Fehlern, bei denen oft nicht klar war in welchem System ein Vector vorliegt, habe ich angefangen die jeweiligen Variablen mit einem Präfix zu versehen, aus dem hervorgeht, in welchem System der Vector vorliegt. Ein Ausdruck
1 | |
kann daher schon deshalb nicht richtig sein, weil hier "loc"ale Koordinaten mit "abs"oluten Koordinaten vermischt werden. Da müssen also Umrechnungen rein.
1 | |
und erst jetzt kann das aus formalen Gründen hinkommen. Da muss ich noch nicht einmal geometrisch überlegen, ob die erste Variante überhaupt richtig sein kann. Die HN sagt mir, dass sie es nicht ist.
Karl Heinz Buchegger schrieb: > Die HN sagt mir, dass sie es nicht ist. das ist aber nicht mehr das, was man heute als HN versteht
Vlad Tepesch schrieb: > Karl Heinz Buchegger schrieb: >> Die HN sagt mir, dass sie es nicht ist. > > das ist aber nicht mehr das, was man heute als HN versteht :-) Das ist aber das, was ursprünglich vom Autor als HN gedacht war.
Karl Heinz Buchegger schrieb: > :-) > Das ist aber das, was ursprünglich vom Autor als HN gedacht war. jep hab ich oben auch schon geschrieben, dass es ursprünglich anders gedacht war
Vlad Tepesch schrieb: > hab ich oben auch schon geschrieben, dass es ursprünglich anders gedacht > war Naja, oder ist das Beispiel von Simonyi (http://msdn.microsoft.com/en-us/library/aa260976(VS.60).aspx) gut lesbar oder gar "clear code" (s.u.) A. K. schrieb: > Microsoft als Vorbild für Programmierkonventionen zu verwenden ist > ohnhin etwas mutig. Denen haben wird immerhin zu verdanken, dass auch > 64-Bit Prozessoren eine Wortbreite von 16 Bits haben und man dank dieser > ungarischen Notation in fast jeder einzelnen verdammten Quellcodezeile > an jene uralten Zeiten erinnert wird, in denen das mal stimmte. Die können (mittlerweile) auch anders... http://referencesource.microsoft.com/netframework.aspx (Referenzquelltexte des .NET-Frameworks) Viel Spaß beim stöbern... Peter Stegemann schrieb: > Das Wort "selbsterklaerend" gehoert in der Informatik verboten - selbst > einfachste Funktionen sind das nicht. "The rationale for the code being the primary source of documentation is that it is the only one that is sufficiently detailed and precise to act in that role... So the first step to clear code is to accept that code is documentation, and then put the effort in to make it be clear. I think this comes down to what was taught to most programmers when they began to program. My teachers didn't put much emphasis on making code clear, they didn't seem to value it and certainly didn't talk about how to do it. We as a whole industry need to put much more emphasis on valuing the clarity of code." http://www.martinfowler.com/bliki/CodeAsDocumentation.html > Wer das glaubt, hat schlicht nicht > genug Erfahrung. Schon triviale Funktionen stecken voller > Randbedingungen, die dokumentiert werden muessen. Wenn sie so viele Randbedingungen haben, sind sie nicht trivial. Ansonsten gilt (etwas übertrieben...): Wenn (wirklich) alle Randbedingungen dokumentiert sind, existiert die Programmiersprache, mit der der Code geschrieben werden sollte, sehr wahrscheinlich nur noch im Museum. Bleibt nur die Möglichkeit, dass, was man zum Zeitpunkt der Erstellung als kritisch gesehen hat, zu dokumentieren. Beispiel: Integerarithmetik, in so gut wie allen Sprachen müsste man dokumentieren, das bei bestimmten Operationen nicht in jedem Fall das gewünschte Ergebnis herauskommt. Bei Ruby müsste man anders (oder gar nicht) dokumentieren, da dort z.B. automatisch von Fixnum auf Bignum gewechselt wird, wenn es zu einem Überlauf kommt usw. http://ruby-doc.org/core/classes/Fixnum.html > Oft ist sogar viel > wichtiger, was eine Funktion nicht kann oder wann sie nicht > funktioniert, als die Beschreibung ihres Hauptzwecks. Richtig.
Gast
#2284259
Arc Net schrieb: > http://www.martinfowler.com/bliki/CodeAsDocumentation.html Wieso glauben Leute eigentlich, wenn man ein Argument verlinken kann, bekaeme es ploetzlich mehr Gewicht? Jeder Honk kann irgendeinen Stuss auf einer Webseite verbreiten - und jeder zweite Honk tut es auch. In Zukunft kannst du ja auf diesen Post hier verlinken: Aus Code kann man nur Eines herauslesen: WAS passiert. Ueber das WARUM sagt Code ueberhaupt nichts. Und deswegen ist Code keine Dokumentation.
Peter Stegemann schrieb: > Arc Net schrieb: > >> http://www.martinfowler.com/bliki/CodeAsDocumentation.html > > Wieso glauben Leute eigentlich, wenn man ein Argument verlinken kann, > bekaeme es ploetzlich mehr Gewicht? Warum sollte ich (mehr oder weniger) eine Übersetzung schreiben und nicht verlinken, wenn ich seine Argumentation für richtig halte? > In Zukunft kannst du ja auf diesen Post hier verlinken: Eher hierauf: http://scalibq.wordpress.com/2011/07/06/source-code-is-not-documentation/ und die Beispiele auseinandernehmen. > Aus Code kann man nur Eines herauslesen: WAS passiert. Ueber das > WARUM sagt Code ueberhaupt nichts. Und deswegen ist Code _keine_ > Dokumentation. Von was reden wir hier: Funktionen in C, nicht über Spezifikationen, Use Cases, User Stories oder Anforderungen etc. die, wenn man es genau nimmt, auch nur sagen was zu passieren hat und nicht warum (und man hätte eine philosophische Diskussion)
Moin, ertmal. Vlad Tepesch schrieb: > Jean Player schrieb: >> lerne erstmal Doxygen zu bedienen. >> Ansonsten würde wohl kaum mein Anhang generiert werden. Wie heisst es so schön in der Physik (actio et reactio). Jaja mein Wortschatz war sehr arg, sry Jung (war von der Arbeit sehr eingenommen in letzter Zeit). > was ich dazu noch sagen wollte: > Ich kann sehr wohl mit Doxygen umgehen. > Ich habe schon recht umfangreiche Dokumentation damit erstellt. > Sogar Fehler im Code gefunden und Fixes vorgeschlagen. Jaja das ich will Dir keiner(Ich) absprechen. Aber ich habe im Notfall lieber doppelt gemoppelt (siehe usb_endp.c) Klar gibt es Warnings in meinem Doxygen Format, ist ja auch selbst gebastelst (mein Favourit zu lesen). Aber Fehler über Doxygen zu finden im Code naja sehr zweifelhaft, die sollte man eher im Code suchen als im Doxygen. > Hier nochmal zum Nachlesen, wegen dem @param: > http://www.stack.nl/~dimitri/doxygen/commands.html#cmdparHabam Super danke, das hätte ich ja nie gewusst ! Du hast Dir schon meinen ScreenShot oben angeschaut hoffentlich. Ich habe meinen Style und du deinen, aber zu erzählen, das ist ein Beispiel wie man es nicht machen soll , ist meiner Meinung nach nur engstirnig. My 5 Cent.
>> Ich habe schon recht umfangreiche Dokumentation damit erstellt. >> Sogar Fehler im Code gefunden und Fixes vorgeschlagen. Naja, mein letztes Problem war ein AT26-32Mbit Flash. Lief unter 6 Mhz SPI Problemlos und laut DatenBlatt sollte der Code bis (aus meinem Gedächtnis) bis 33 Mhz funktionieren. Siehe da ab 18 Mhz spinnt er sporadisch rum, also Timing anpassen, statt 0x03 , also 0x0B senden mit Dummy byte. Also das alles siehst Du natürlich ausm Doxygen, Prost.
Jean Player schrieb: > Klar gibt es Warnings in meinem Doxygen Format, ist ja auch selbst > gebastelst (mein Favourit zu lesen). > Aber Fehler über Doxygen zu finden > im Code naja sehr zweifelhaft, Es hat niemand behaupted, dass Doxygen fehler im Code findet. Es findet, wenn man es so benutzt, wie es gedacht ist, Fehler/Inkonsistenten in der Dokumentation, zB. vergessene Parameter, überflüssige Parameter. Das hilf enorm, wenn man am Code etwas geändert hat und vergessen hat die Dokumentation anzupassen. Jean Player schrieb: > Super danke, das hätte ich ja nie gewusst ! bitte, Google hilf manchmal > Du hast Dir schon meinen ScreenShot oben angeschaut hoffentlich. > Ich habe meinen Style und du deinen, aber zu erzählen, das ist ein > Beispiel wie man es nicht machen soll , ist meiner Meinung nach nur > engstirnig. Du misbrauchst hier aber ein Werkzeug, indem du es so benutzt, wie es nicht gedacht ist und empfiehlst dies auch noch anderen Leuten. Das ist, als wenn man ein Schraubendreher als Meißel benutzt und anderen erzählt, dafür sei er gedacht obwohl man es besser weiß. Ich wollte lediglich darauf hinweisen, dass man sich an dieser Aussage kein Beispiel nehmen soll, weil es eben keins ist, wie man das Werkzeug typischerweise benutzt. Jean Player schrieb: > Naja, mein letztes Problem war ein AT26-32Mbit Flash. Lief unter 6 Mhz > SPI Problemlos und laut DatenBlatt sollte der Code bis (aus meinem > Gedächtnis) bis 33 Mhz funktionieren. Siehe da ab 18 Mhz spinnt er > sporadisch rum, also Timing anpassen, statt 0x03 , also 0x0B senden mit > Dummy byte. > Also das alles siehst Du natürlich ausm Doxygen, Prost. Das hat überhaupt nix mit dem Thema zu tun. Inwiefern hätte dir denn hier deine seltsame Verwendung von Doxygen weitergeholfen?
Antwort schreiben
Bitte melde dich an, um einen Beitrag zu schreiben.