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.
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.
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 ...
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
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.
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
* Sets the given brightness and ignores further changes
3
* of brightness until pwm_release_brightness is called.
4
*
5
* @details Other changes of brighness (other than with this function)
6
* will be recognized but not considerd.\n
7
* The change takes effect after pwm_release_brightness
8
* was called.
9
* @param val the brightness to set [0..255]
10
*/
11
externvoidpwm_lock_brightness_val(uint8_tval);
oder
1
/**
2
* sets the display to the given state
3
* @details This function can be used to set a special image on the display independent of current time
4
* This is especially usefull for provide some feesback for user interactions
5
* eg. set time, or set Color
6
* f_call: extern irregularly (internal: when called setNewTime)
7
* @param i_showStates defined which words should be shown at all
8
* @param i_blinkstates defines which words should blink with DISPLAY_BLINK_INT_ms
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.
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.
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,
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. ;-)
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.
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...
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.
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
if((data.flags&DF_successfulRead)// data processing was successful
2
&&(data.flags&DF_successfulStored)
3
&&(data.flags&DF_successfulSend))
4
{...}
besser:
1
if(dataProcessingSuccessful(&data))
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
> 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ß
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
> 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.
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 ;)
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
externvoidpwm_lock_brightness_val(uint8_tval);
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
locCorner=absInputPos*locNormal*displacement;
kann daher schon deshalb nicht richtig sein, weil hier "loc"ale
Koordinaten mit "abs"oluten Koordinaten vermischt werden. Da müssen also
Umrechnungen rein.
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.
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.
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?
Thread beobachten
Seitenaufteilung abschalten