Beta-Tester für C++11 UML State Machine Framework yasmine gesucht



  • Der Knackpunkt ist dass eine Funktion mit dieser Signatur überhaupt keine Doku braucht. Wozu sollte man dann eine schreiben?

    Und was genau soll an "source" besser sein als an "document"? Wenn schon dann "sourceDocument". Nur bei einer Funktion die nur ein Document nimmt, und dieses ganz offensichtlich ausgedruckt wird, und daher ganz offensichtlich das "source" Dokument ist... also man kanns auch übertreiben.

    Einen Rasterizer als "rules" oder "raster" zu bezeichnen ist 1A Blödsinn.
    Genau so wie den Printer als "output" zu bezeichnen. Wahrscheinlich war hier "sink" (=etwas wo man Dinge hinein tun kann) und nicht "output" (etwas was von einem Prozess generiert wird) gemeint. Oder "outputDevice".

    Ist aber genau so Quatsch. Wieso vorgaukeln dass etwas irgendwie besonders generisch wäre (source, rules, outputDevice), wenn es in Wirklichkeit sehr konkret ist (document, rasterizer, printer)?

    Das ist doch bloss der krampfhafte Versuch etwas zu vermeiden was man irgendwann mal (fälschlicherweise) als "pfui" kategorisiert hat. Nämlich Objekte gleich zu nennen wie ihren Typ. Mein Erfahrung diesbezüglich ist: Je mehr man seine Programme sinnvoll factored, und je besser man seine Klassen benennt, desto häufiger macht es Sinn seine Objekte genau so zu nennen wie ihr Typ.
    Dass das als generelle Regel völlig schwachsinnig wäre ist auch klar. Ich sagen nur: es kommt nicht so selten vor dass es Sinn macht.



  • In diesem Fall kann man aus dem Funktionsnamen und Allgemeinwissen leicht herleiten, wofür die Parameter wohl gut sind. Das System bricht aber sofort zusammen, wenn es um Typen wie Integer, Zeiger, Strings geht oder mehrere Parameter denselben Typ haben.

    Beispiel:

    void Copy(Document document1, Document document2, bool boolean);
    

    Ich will nicht sagen, dass bool ein sinnvoller Parametertyp ist, aber Leute machen so etwas und dann sollte der Parameter wenigstens einen sinnvollen Namen haben. Wenn man anfängt die Parameterbenennung zur Ermessenssache zu machen, produzieren die faulen Entwickler Müllnamen und alle müssen darunter leiden. Deswegen bin ich dafür pauschal sprechende Namen zu verwenden.



  • TyRoXx schrieb:

    In diesem Fall kann man aus dem Funktionsnamen und Allgemeinwissen leicht herleiten, wofür die Parameter wohl gut sind. Das System bricht aber sofort zusammen, wenn es um Typen wie Integer, Zeiger, Strings geht

    Bei manchen Funktionen, ja. Bei anderen nicht.

    string ToString(int integer); // Weil "int int" halt nicht geht
    string ToLower(string str);
    ...
    

    Andere Namen machen hier keinen Sinn. (Nicht dass automatisch alle anderen Namen schlechter wären, "value" oder "number" wären natürlich auch OK - gleichwertig. Aber nicht wirklich besser.)

    TyRoXx schrieb:

    oder mehrere Parameter denselben Typ haben.

    Beispiel:

    void Copy(Document document1, Document document2, bool boolean);
    

    Ja, irgendwie logisch.
    Und?
    Mein Argument war:

    hustbaer schrieb:

    Ja, man sollte Variablen sinnvoll benennen, und sinnvoll ist nicht immer der Typname.
    Allerdings oft halt ... doch.

    Dem hast du widersprochen und mir unterstellt dass in meinem Gedankenmodell etwas schief sei. Und jetzt kommt der Strohmann dass ich behauptet hätte dass es immer Sinn macht? Oft = immer? Wo ich 1 Satz vorher explizit schreibe dass es NICHT immer Sinn macht? Wirklich?



  • ps
    Was du damit meinst

    TyRoXx schrieb:

    Man muss sich schon entscheiden, ob ein "printer" abstrakt oder konkret ist.

    verstehe ich nicht.
    Kanns du ein Beispiel schreiben wie eine sinnvolle Benamsung deiner Meinung nach aussehen würde? Also 1x für wenn man sich für "abstrakt" entscheidet und 1x für wenn man sich für "konkret" entscheidet.

    BTW: Mir fällt gerade auf dass das const beim Printer Quark ist. Sorry, war keine Absicht. Falls das Misverständnisse verursacht hat tut es mir leid.
    Also was ich meinte war schon
    void PrintDocument(Document const& document, Rasterizer const& rasterizer, Printer& printer);
    (Und beim Rasterizer könnte es evtl. auch sinnvoll sein das const wegzulassen.)



  • TyRoXx schrieb:

    Das ist eine vernünftige Benennung. Parameter oder Variablen nur nach ihrem Typ zu benennen ist eine Unsitte, die man zugunsten der Dokumentation vermeiden sollte.

    Wer meint, dass Document const& document die bestmögliche Benennung ist, schreibt wohl auch solche Kommentare:

    /** \brief Prints the document.
     \argument document the document
     \argument rasterizer the rasterizer
     \argument printer the printer
     \returns void
    */
    void PrintDocument(Document const& document, Rasterizer const& rasterizer, Printer const& printer);
    

    Wenn ein Interface den gleichen Namen wie eine Implementierung bekommen soll, ist zu 99% etwas schief im Gedankenmodell. Man muss sich schon entscheiden, ob ein "printer" abstrakt oder konkret ist.

    Du willst die Parameter-Namen nur anders (schlechter) wählen, damit du eine Doku sinnvoll schreiben kannst? 😕 Normalerweise ist es doch umgekehrt: man will keine Doku schreiben müssen, weil man gute Funktions- und Parameter-Namen erdacht hat. Der Source-Code hat immer höhere Priorität in der Klarheit als die Doku. Doku nur dann, wenn Source schlecht.
    Wozu also noch eine Parameter-Doku wenn es selbsterklärend ist? Lass sie doch weg. Zumindest die Parameter. Die Brief-Description kann ja bleiben.



  • Artchi schrieb:

    😕 Normalerweise ist es doch umgekehrt: man will keine Doku schreiben müssen, weil man gute Funktions- und Parameter-Namen erdacht hat. Der Source-Code hat immer höhere Priorität in der Klarheit als die Doku. Doku nur dann, wenn Source schlecht.
    Wozu also noch eine Parameter-Doku wenn es selbsterklärend ist? Lass sie doch weg. Zumindest die Parameter. Die Brief-Description kann ja bleiben.

    Die vernünftigen Parameternamen sind die Dokumentation.



  • @Artchi
    Ich denke TyRoXx sieht das mit der Doku schon gleich wie wir.
    Er wollte nur wieder mal mir dagegenreden, und hat mir dann - weil er gerade schon dabei war - noch schnell unterstellt dass ich vermutlich auch Undocumentation schreibe.



  • hustbaer schrieb:

    Beispiel:

    void PrintDocument(Document const& document, Rasterizer const& rasterizer, Printer const& printer);
    

    Was soll man hier umbenennen?

    Oberflächlich muss man da gar nichts umbenennen.

    Und es muss auch gar nichts in die Doku. Im Gegenteil! Supertriviale Doku bremst nur beim Lesen und hat wie jede Doku die Tendenz, nach ein paar Bugfixes zu lügen wie Kohl.

    Naja, warum der Rasterizer seinen Status nicht ändert, wenn er was malt, das muss in die Doku! Hat der Rasterizer lauter mutable members? Oder ist er ein Wrapper für pro Seite ausgehobene PageRasterizers? Oder ist er gar nur ein Prototyp? Wenn man es in die Doku des Rasterizer schreibt, dann ist das zwar sehr gut, aber jeder Leser hier wird trotzdem stolpern. Der sollte hier schon Rasterizer const& rasterizerPrototype oder RasterizerMaker const& rasterizerMaker sein, oder?
    Aber was mich völlig fertig macht, ist der Printer, der seinen Status nicht ändert, wenn er druckt.



  • @volkard
    Ja, hast natürlich vollkommen Recht. Das const beim Printer war definitiv Quatsch und das beim Rasterzier ist zumindest fragwürdig.

    hustbaer schrieb:

    BTW: Mir fällt gerade auf dass das const beim Printer Quark ist. Sorry, war keine Absicht. Falls das Misverständnisse verursacht hat tut es mir leid.
    Also was ich meinte war schon
    void PrintDocument(Document const& document, Rasterizer const& rasterizer, Printer& printer);
    (Und beim Rasterizer könnte es evtl. auch sinnvoll sein das const wegzulassen.)



  • Hallo zusammen,

    das nächste Release (0.2.0) von yasmine steht bereit.

    Die wichtigsten Neuerungen:

    • Die Lizenz referenziert und/oder erwähnt die MIT-Lizenz nicht mehr, sondern enthält alle Regelungen selbst.
    • Benamung:
    • Bei Klassen sind die Präfixe t_ und i_ entfallen. Bei Interface-Implementierungspaaren hat die Implementierung den Postfix _impl.
    • Bei Funktionsparametern wurde aus p_foo _foo, bei Membervariablen wurde aus m_foo foo_ und bei globalen Variablen aus g_foo FOO.
    • Einführung von Sammel-Headern, damit nicht so viele includes notwendig sind.
    • Logging kann komplett per Definition von Y_NO_LOGGING deaktiviert werden.
    • Neue Features:
    • Simple States mit asynchronem Do: Die Aktion läuft in einem eigenen Thread, solange bis der Zustand verlassen wird.
    • Error Handling für Simple States: Definieren von Events, die, im Falle des Auftretens einer Exception während des Ausführens des Do, abgefeuert werden sollen.

    Außerdem gibt es auf der yasmine-Homepage jetzt rechts oben einen Schalter, mit dem man das Theme/Style Sheet umschalten kann (dunkler Hintergrund/heller Hintergrund).


Anmelden zum Antworten