Code Styleguide


  • Mod

    Ich denke wir sollten rasch einen style guide für PrettyOS schaffen. Hier der Link zu dem von Tyndur, den wir als Basis für unsere Diskussion verwenden können:
    http://git.tyndur.org/?p=tyndur.git;a=blob;f=doc/codestil.txt;h=da5c05be62085bd6addd3dafc094029fd293fe64;hb=HEAD

    Themen:
    Einrueckung
    Maximale Zeilenlaenge
    Platzierung der geschweiften Klammern
    Platzierung von Leerzeichen
    Benennung
    Kommentare

    Ich bin übrigens dafür, alle Kommentare, Funktions-, Variablennamen in Englisch zu wählen/schreiben.

    Wir müssen hierüber entscheiden:

    if (file == NULL) {
        return NULL;
    }
    
    if (file == NULL) 
    {
        return NULL;
    }
    

    Ich tendiere zu Letzterem, auch wenn eine Zeile verloren geht, weil ich die Klammern auf einer Spalte übereinander sehen möchte. Bei tyndur geht dies trotz Regel kreuz und quer.

    Bei Zeigern bevorzuge ich - analog tyndur - char* p anstelle char * p oder char *p, weil mich Letzteres zu sehr an den Dereferenzierungs-Operator (Inhalt von ...) erinnert.
    Ich schreibe auch schon immer for(...) anstelle for (...), aber das sind Kleinigkeiten, bei denen man sich umgewöhnen kann.

    Ich würde auch vorschlagen, den Styleguide in Englisch zu verfassen.
    Wie wird das allgemein gesehen?



  • Den Codestil von tyndur find ich soweit ganz gut. Ich verwende zwar selber lieber CamelCase, aber in C machen die Unterstriche schon Sinn, wenn man eine Variable mit einem Prefix für den jeweiligen Bereich versieht.



  • Ich bin auch dafür, den Sourcecode plus Kommentare komplett in Englisch zu verfassen.
    Bei den Konventionen der Kommentare würde ich eher mehr Freiheiten lassen. Im Tyndur-Sourcecode hat das mit den Doxygen-Kommentaren auch nicht so wirklich geklappt, teils fehlend, teils falsch/veraltet. Die geöffnete geschweifte Klammer gehört m.E. immer in die nächste Zeile, so viel Platz ist dann doch noch. Einrückung ist ein heißes Thema. Leerzeichen und Zeilenlänge sollten meiner Meinung jedem selbst überlassen sein.

    Ich fände es schade, auf Großbuchstaben zu verzichten, ich mag PascalCase für Typen, ist in C aber ja leider nicht gängig.


  • Mod

    Ich fände es schade, auf Großbuchstaben zu verzichten, ich mag PascalCase für Typen, ist in C aber ja leider nicht gängig.

    Ich habe es bisher nicht ganz einheitlich gehalten, stelle aber fest, dass ich so etwas wie "sleepSeconds" oder "sleepMilliSeconds" aus dem Gedächtnis öfters falsch geschrieben habe. Wenn man konsequent Underscores und Kleinschreibung verwendet ist dies diesbezüglich ein Vorteil. "systemTimer_setFrequency" ist auch nicht optimal zum Einprägen, daher könnte "system_timer_set_frequency" von Vorteil sein.



  • Erhard Henkes schrieb:

    Wenn man konsequent Underscores und Kleinschreibung verwendet ist dies diesbezüglich ein Vorteil. "systemTimer_setFrequency" ist auch nicht optimal zum Einprägen, daher könnte "system_timer_set_frequency" von Vorteil sein.

    Vielleicht steckt hinter dem underscore da mehr. Ist vielleicht das gemeint, was man in anderer Sprache als systemTimer::setFrequency schreiben würde? Vielleicht kann man mit Unterstrichen sozusagen Namensräume basteln. Dann müßte man einführen, daß underscores in Bezeichnern nur diesen Zweck haben.



  • Ich bin einverstanden mit

    if (file == NULL)
    {
        return NULL;
    }
    

    Aber das ist eine religöse Angelegenheit, in der du (Erhard) notfalls ein Machtwort sprechen musst, wenn es uns die Einheitlichkeit wichtig ist.

    Ich mache Einrückungen immer mit Leerzeichen und zwar mit 4 davon.

    Ich würde auch vorschlagen, den Styleguide in Englisch zu verfassen.

    Mir persönlich ganz egal. Da kommt es wahrscheinlich auf die Zielgruppe an. Wenn wir viele deutschsprachige Jugendliche erreichen wollen, könnte das auch nach hinten los gehen, wenn wir unser Englisch nicht konsequent halbwegs einfach halten. Immerhin kenne ich die Tutorials auf www.henkessoft.de nur deshalb, weil ich damals mit den englischen Tutorials noch überfordert war.



  • Vielleicht kann man mit Unterstrichen sozusagen Namensräume basteln. Dann müßte man einführen, daß underscores in Bezeichnern nur diesen Zweck haben.

    Das ergibt Sinn. Allerdings müssen wir auch das hier vermeiden:
    http://thedailywtf.com/Articles/CodeThatDocumentsItselfSoWellItDoesNotNeedComments.aspx



  • Zeilenlänge: ich bin definitiv dafür, die üblichen 80 Zeichen einzuhalten.


  • Mod

    80 Zeichen hatte ja schon mein Commodore C64 in den 80er Jahren.

    Die 80 Zeichen pro Zeile habe ich bisher im Sourcecode überschritten. Durch Einrückungen fangen manche Zeilen ja erst bei 20 an. Daher bin ich für das Zulassen von mehr als 80 Zeichen pro Zeile (incl. Leerzeichen).

    Was wäre denn die nächste sinnvolle Marke, die sich an einem Drucker ausrichtet? 😕

    Immerhin kenne ich die Tutorials auf www.henkessoft.de nur deshalb, weil ich damals mit den englischen Tutorials noch überfordert war.

    Das ist ein überzeugendes Argument. Da der Styleguide bezüglich des Textes (ohne Beispiele) erwartungsgemäß nicht allzu lang sein wird, kann man ihn vielleicht auch in zwei Sprachen führen, also deutsch und englisch.
    Wir könnten den Styleguide zunächst in deutsch entwickeln und verabschieden, dann würde ich ihn anschließend ins Englische übersetzen, um Hürden für vorwiegend englisch-sprachige Mitglieder möglichst niedrig zu halten. Bezüglich englisch würde ich - wegen Gewöhnung - die US-amerikanische Schreibweise wählen.



  • volkard schrieb:

    Vielleicht kann man mit Unterstrichen sozusagen Namensräume basteln.

    Gute Idee! Dann muß man sich beim Quellcode lesen nicht immer einen Wolf suchen. 🙂


  • Mod

    Dann müsste man aber auch die Mischung zulassen, eben "systemTimer_setFrequency". Oder sehe ich das verkehrt?



  • Erhard Henkes schrieb:

    Dann müsste man aber auch die Mischung zulassen, eben "systemTimer_setFrequency". Oder sehe ich das verkehrt?

    Ich dachte nur an die Namensräume, die schon bei den file-Funktionen fopen fclose fprintf benutzt wurden, die würden wir heute wohl file_open file_close file_printf schreiben.
    Entsprechend wäre dann die Mischform systemTimer_setFrequency auch notwendig. Wobei man aber auch die Bälle flach halten sollte und nicht mit kernel_tools_time_systemTimer_setFrequency rumtoben. 🙂


  • Mod

    Gibt es hier auch eine sinnvolle Möglichkeit dies einzusetzen, ohne Großbuchstaben zu verwenden? (analog tyndur)



  • Erhard Henkes schrieb:

    Gibt es hier auch eine sinnvolle Möglichkeit dies einzusetzen, ohne Großbuchstaben zu verwenden? (analog tyndur)

    Doppelte sind namespacetrenner?
    system_timer__set_frequency()



  • Wenn ich eine Funktion namens "systemTimer_setFrequency" in einer Übersetzungseinheit namens "systemTimer.c" finde, würde es mir als "Namensraum" schon reichen. (Geht auch ohne Großbuchstaben).


  • Mod

    Doppelte sind namespacetrenner?

    Das mit dem doppelten Underscore hatte ich mich nicht getraut vorzuschlagen. 😃

    Geht auch ohne Großbuchstaben

    Wie würdest Du das genau machen?



  • Erhard Henkes schrieb:

    Gibt es hier auch eine sinnvolle Möglichkeit dies einzusetzen, ohne Großbuchstaben zu verwenden? (analog tyndur)

    Möglicherweise fehlen bei tyndur einfach ein paar doppelte, und zwar stets zwischen klassenname und methodenname.

    //zwei _ von mir zugefügt
    struct cdi_net_driver {...};
    void cdi_net_driver__init(struct cdi_net_driver *driver);
    void cdi_net_driver__destroy(struct cdi_net_driver *driver);
    

    aber was ist

    //original
    void cdi_pci_alloc_ioports(struct cdi_pci_device *device);
    

    eigentlich?

    Vielleicht nur eine

    //geklärt?
    void cdi_pci_device__alloc_ioports(struct cdi_pci_device *device);
    

    ?



  • Wie würdest Du das genau machen?

    Wenn PrettyOS einen Systemtimer hat, dann ist er in der "systemtimer.c" definiert und das "Präfix" "systemtimer_" darf außerhalb der systemtimer.c nicht für Bezeichner verwendet werden.



  • +gjm+ schrieb:

    Wie würdest Du das genau machen?

    Wenn PrettyOS einen Systemtimer hat, dann ist er in der "systemtimer.c" definiert und das "Präfix" "systemtimer_" darf außerhalb der systemtimer.c nicht für Bezeichner verwendet werden.

    Dafür meine Stimme. Nur nicht zu viele Reglen, das alles macht sonst keinen Spaß mehr...



  • Erhard schrieb:

    80 Zeichen hatte ja schon mein Commodore C64 in den 80er Jahren.

    Die 80 Zeichen pro Zeile habe ich bisher im Sourcecode überschritten. Durch Einrückungen fangen manche Zeilen ja erst bei 20 an. Daher bin ich für das Zulassen von mehr als 80 Zeichen pro Zeile (incl. Leerzeichen).

    Was wäre denn die nächste sinnvolle Marke, die sich an einem Drucker ausrichtet? 😕

    Ich hatte die 80 Zeichen bis jetzt immer aus religiösem Glauben eingehalten, Argumente habe ich dazu keine. Und Ärger mit den Einrückungen hatte ich auch schon. 🙄 Deshalb wollte ich einige Zeit lang auf 2 Spaces pro Einrückung umsteigen, aber das hat bis jetzt nicht hingehaut.

    Ich kenne leider sonst keine sinnvolle Marke. Letztlich ist das aber gar nicht so wichtig, weil man Sourcecode ja hervorragend automatisch neuformatieren kann. Nur zu lange Stringliterale erfordern dann etwas mehr Aufmerksamkeit.

    Das wichtigere Thema ist sicherlich die Namenskonvention. Ich befürchte, daß Volkard unabsichtlich ein wenig von unserem guten alten Sprachenkrieg hier hereintragen könnte.

    Können wir uns auf folgenden Grundsatz einigen?
    Eine konsistente Namenskonvention einzuhalten ist mehr eine Kunst als etwas, das man mechanisch umsetzen kann.

    Nachtrag zu den Zeilenlängen und den Druckern:
    Ich habe hier keinen funktionierenden Drucker herumstehen, und am Bildschirm läßt man sich leicht verwirren. Der Gnome-Editor in den Ubuntu-Voreinstellungen druckt bis ca. 100 Zeichen pro Zeile:
    http://i37.tinypic.com/dzcz2g.png


Anmelden zum Antworten