Style Guides

[flashpixx]

Hallo,

mich würde einmal interessiere welche Style Guides ihr verwendet. Z.B. welche Benennungsvorschriften im Quellcode gibt es bei welcher Sprache, wie sehen Datei- / Verzeichnis Strukturen aus, etc.

Mir wäre es wichtig, wenn jeder das ganze auch dahin schildern könnte, wie sinnvoll diese Vorschriften sind bzw. wo sie evtl auch hinderlich sind.

Danke

fpx

[Gast runtimeterror]

Mal ein paar Auszüge aus dem, was ich für Java als Best-Practice empfinde:

Dateistruktur:

Mein Projekt (Hauptordner)

    + src (Java-Quelltexte)

    + res (Ressourcen: Icons, I18N, Mediendateien, Datenbanken, xml, ...)

    + bin (Ausgabeverzeichnis für class-Dateien)

    + doc (Pflichtenhefte, Dokumentation (keine Quelltextdokumentation - die ist immer inline!))

    + dev (Entwicklungsressourcen, Auswertungen, Zwischenstände, Rohdaten, Scratchpad, Projektplanung, ...)

Was den Quelltext angeht:

- Code-Blocke so klein halten, dass so gut wie keine Inline-Kommentare notwendig sind. Nach Möglichkeit sollte alles über JavaDoc-Comments abgewickelt werden.

- Bezeichner immer auf US-Englisch (außer fachliche Begriffe, die der Auftraggeber verwendet, falls die Anwendung einsprachig wird)

- Abkürzungen als ein Wort beim Camel- oder Pascal-casing: (myUrl statt myURL). Das ermöglicht die automatisierte Umwandlung in andere Notationen (-> MY_URL)

- Klassenname in Objekteigenschaften nicht wiederholen (Human.name statt Human.humanName)

- Alle Warnungen und Hinweise der IDE einschalten und nur diejenigen wieder abschalten, die für das Projekt nicht zutreffend sind (bei mir meist "Externalize all Strings"). Alle Warnungen sind abzuarbeiten oder in Einzelfällen (bei mir meist "Undocumented empty code-block") per Annotation zu ignorieren. Auf diese Weise findet man extrem viele Flüchtigkeitsfehler.

- lange und sprechende Bezeichner wählen (für Tippfaule gibt's die Autocompletion der IDE)

- Refactoring benutzen! Falls sich ein Bezeichner als im Nachhinein als unsinnig erweist, so sollte er umbenannt werden (sofern die Projektgröße das noch zulässt).

- keine einzige Deprecated-Methoden/Klassen verwenden!

- So wenige Type-Casts wie möglich verwenden

- Lieber "throws" als leere catch-Blöcke

- Beim Umwandeln von String in byte[] und umgekehrt IMMER ein Charset angeben!

- Automatischen Zeilenumbruch bei 80 Zeichen in der IDE abschalten (Außer für Kommentarblöcke). Heutige Monitore sind breit genug. Der Entwickler sollte durch Hilfsvariablen für kurze Zeilen sorgen. Es ist beim Überfliegen von Quelltext immer schwierig umgebrochene Zeilen zu lesen.

- Immer mit Tab einrücken (innerhalb der Zeile aber nie für Bündigkeit sorgen)

- Die early! Die Methode/Block so früh wie möglich verlassen (break, continue, return, throws). Das vermeidet unleserliche if-Block-Schachtelungen und den Einsatz von Steuervariablen mit unleserlichen Abbruchbedingungen in Schleifen.

- Ternären Operator immer einsetzen, wenn sich dadurch ein if-Block einsparen lässt. Ternären Operator niemals schachteln.

- Immer int (statt long, byte, short) verwenden, es sei denn es gibt konkrete Gründe davon abzuweichen. Java ist darauf optimiert.

- if/while/for/etc. immer als Block ausführen, nicht als Einzelstatement (Ausnahme sind einfache Abbrüche mit break, return, throws, continue)

- Wenn möglich immer alles in UTF-8; auch den Quelltext

Soweit erstmal alles, was mir spontan in den Sinn kommt.

Viel Spaß damit und guten Rutsch!

[pintman]

Ein sehr schöne und ausführliche Darstellung für Smalltalk findet sich in dem mittlerweile freien Buch "Smalltalk With Style".

http://stephane.ducasse.free.fr/FreeBooks/WithStyle/SmalltalkWithStyle.pdf

Viele der dort vorgestellten Konzepte sind in späteren OO-Sprachen eingeflossen und lassen sich leicht auf diese übertragen.

[Aras]

In meinem Unternehmen existieren keine Style Guides. Ich finde StyleGuides sinnvoll und denke dass unser Unternehmen langfristig ein CodingStandard erstellen wird.

Insofern finde ich diese Diskussion schon interessant.

[flashpixx]

@runtimeterror: Vielen Dank, Deine Beschreibung ist im Grunde fast identisch zu meiner, nur dass ich da ich aktuell mit C++ arbeite, noch ein paar Sachen verändert habe.

Ich benutze noch zusätzlich für die Benennung von Variablen / Member eine von der ungarischen Notation abgewandelte Form:

Alles was als Parameter in eine Methode hinein / hinaus geht, wird p_, Member mit m_ und lokale Variablen l_ als einem Prefix bezeichnet, und ich nutze eben Doxygen für die Kommentierung, was aber Javadoc ähnlich ist. Ich nutze generell keine Tabs, sondern diese werden in 4 Spaces umgewandelt. Gerade bei Python können Tabs & Spaces durchaus auch zu fehlerhafter Codeausführung führen.

@pintman: Die Smalltalk Beschreibung deckt sich ja zum größten Teil mit dem was runtimeterror beschrieben hat

[Pixie]

In meinem Unternehmen existieren keine Style Guides. Ich finde StyleGuides sinnvoll und denke dass unser Unternehmen langfristig ein CodingStandard erstellen wird.

Insofern finde ich diese Diskussion schon interessant.

dito.

Gerade runtimeterrors Punkt mit den kleinen Codeblöcken wird bei uns gerne anders herum gehandhabt. Ich halte die Codeblöcke klein, nutze Refactoring um Methoden zu extrahieren und unser Chef findet das unleserlich und es ist ihm zu aufwändig, im Code dann zur Methode zu springen... also nimmt er Methoden, die nur ein Vorkommen haben, komplett an de Aufrufstelle wieder auf. Zum Haareraufen.

Irgendwann hat ein Kollege GhostDoc entdeckt und seitdem haben wir für alles und jeden Quellcodekommentare. Nicht immer sinnvoll, weil die automatisiert generierten Kommentare nicht überarbeitet werden, aber wir haben jetzt kommentierten Quellcode, aus dem mit Sandcastle eine Doku generiert werden kann. Okay, die Doku wäre sinnbefreit, weil die Kommentare öfter sinnbefreit sind. Aber wir können jetzt eine Doku generieren.

[flashpixx]

Danke Pixie, GhostDoc kannte ich nicht, aber ist mal etwas nettes.

Ich suche im Moment ein paar sinnvolle Ideen, die dann verwenden kann. Da ich C++ inkl Datenbank für eine cross-plattform Software verwende, brauche ich eben einen Styleguide, der auf allen Plattformen funktioniert und auch zu gleichen Ergebnissen führt (z.B. UTF8 für die Quellcodedateien).

Was ich noch machen möchte, da ich mit Git arbeite mit Hilfe der Githooks im zentralen Repo eben die Codes überprüfen möchte und Pushes ablehne, die nicht dem Standard entsprechen. Benennung kann man mit Hilfe von regulären Ausdrücken prüfen, die Ausgabe von Doxygen kann man verwenden um fehlende Kommentierung zu finden, Einrückung wird aber schon etwas schwieriger, weil dafür eine Typ-2 Grammatik braucht

[lilith2k3]

Clean Code Developer - Clean Code Developer

Clean Code: A Handbook of Agile Software Craftsmanship (Robert C. Martin): Amazon.de: Robert C. Martin: Englische Bücher

The Clean Coder: A Code of Conduct for Professional Programmers (Robert C. Martin): Amazon.de: Robert C. Martin: Englische Bücher

beschreibt, wie ich versuche meinen Code zu strukturieren.

[flashpixx]

Die Links kenne ich schon und nutze ich auch. Die interessante Frage wäre, was für Guides würdet ihr verwenden, wenn man unterschiedliche Entwickler mit unterschiedlichen Kenntnissen und noch aus unterschiedlichen Sprachen hat. Sprich vom Anfänger bis zum professionellen Entwickler alles vertreten ist.

Ich fange einen Großteil der Styleguides durch meine Hook im Repo ab, aber aktuell möchte ich einige Punkte überdenken, da ich festgestellt habe, dass Anfänger sich mit manchen Dingen schwer tun. Die optimale Lösung gibt es ja eh nicht, nur halte ich es auch nicht für sinnvoll einem Anfänger einfach eine Doku an die Hand zu geben und zu sagen "lies es und halte dich dran".

Ich kann alle Punkte, in meinen Styleguides erklären, d.h. warum welche Punkt sinnvoll sind, nur gerade bei Anfängern stelle ich häufig fest, dass sie immer nur einen Ausschnitt der Regeln real umsetzen, so dass z.B. Code oft nicht ohne Hilfe ins Repo eingecheckt werden können.

Bearbeitet 1. Januar 2013 von flashpixx

[pintman]

Vielleicht könnte man die Anfänger mit Pair-Programming in die IDE, das Framework und auch die Style-Guides einführen.

[Pixie]

Die Links kenne ich schon und nutze ich auch. Die interessante Frage wäre, was für Guides würdet ihr verwenden, wenn man unterschiedliche Entwickler mit unterschiedlichen Kenntnissen und noch aus unterschiedlichen Sprachen hat. Sprich vom Anfänger bis zum professionellen Entwickler alles vertreten ist.

Für VisualStudio gibt es das Plugin ReSharper. Zum einen macht es sinnvolle Vorschläge, wie man den Code umformuleiren könnte, gibt Hinweise auf Unsauberkeiten oder mögliche Fehlerquellen und: Man kann eigene Styleguides formulieren. Diese werden teilweise automatisch umgesetzt, z.B. bei Dingen wie geschweifte Klammer am Ende der Zeile oder am Anfang einer neuen, es weist aber auch auf Namen hin, die nicht dem StyleGuide entsprechend gestaltet sind. Das ganze hat wegen der Hinweise also auch einen Lern- und Erziehungseffekt.

[flashpixx]

Für VisualStudio gibt es das Plugin ReSharper.

Hast Du dafür eine Quelle? So etwas klingt sehr gut.

Aktuell muss ich eine eigene IDE entwickeln, in der Lua programmiert wird. Die IDE selbst wird in C++ mit Qt entwickelt, zusätzlich kommt dazu noch ein Dämon, der die Berechnungen durchführt und eine Datenbank, die IDE mit Service verbindet.

Die Datenbank enthält Trigger, Stored Procedures, die IDE eben die ganzen Qt Strukturen und der Service ist Multicore (MPI) und Multithread als crossplattforme Software ausgelegt. Zusätzlich können in die IDE, wie auch den Service DLLs als Plugins eingebunden werden. Als Buildsystem nutze ich Scons, das Python basiert ist (und auch durch Programmierung erweitert wird).

Die IDE für die Entwickler ist somit völlig individuell (ich persönliche nutze XCode unter OSX). Im Moment prüfe ich z.B. Kommentierung via Doxygen bei den Git Hooks, aber um die einzelnen Code Strukturen zu prüfen und in die Hooks einen Check zu implementieren, bin ich noch nicht gekommen. Hätte da jemand einen Vorschlag?

Ich möchte halt vermeiden, dass das der Code aus dem Ruder läuft, weil ich wechselnde und unterschiedliche Entwickler habe und manuell das zu prüfen, ist jetzt kaum noch möglich. Mir würde es erst einmal reichen, wenn ich C++ Codes auf Styleguides prüfen kann, d.h. Benennung, Einrückung etc. D.h. ich bräuchte eine schnell zu konfigurierende technische Möglichkeit.

Pair-Programmierung finde ich eine sehr gute Idee, das möchte ich auf jeden Fall umsetzen, aber ich brauche zusätzlich eine technische Unterstützung.

[Ulfmann]

Wir richten uns weitestgehend nach diesem Guide (die erste 3 Abschnitte beziehen sich auf Ruby):

Dan Kubb's Ruby Style Guide

You may not like all rules presented here, but they work very well for me and have helped producing high quality code. Everyone is free to code however they want, write and follow their own style guides, but when you contribute to my code, please follow these rules:

Formatting:

Use ASCII (or UTF-8, if you have to).

Use 2 space indent, no tabs.

Use Unix-style line endings.

Use spaces around operators, after commas, colons and semicolons, after { and before }.

No spaces after (, [ and before ], ).

Align when and else with case.

Use an empty line before the return value of a method (unless it only has one line), and an empty line between defs.

Use YARD and its conventions for API documentation. Don't put an empty line between the comment block and the def.

Use empty lines to break up a long method into logical paragraphs.

Keep lines fewer than 80 characters.

Strip trailing whitespace.

Syntax:

Use def with parentheses when there are arguments.

Never use for, unless you exactly know why.

Never use then, except in case statements.

Use when x then ... for one-line cases.

Use &&/|| for boolean expressions, and/or for control flow. (Rule of thumb: If you have to use outer parentheses, you are using the wrong operators.)

Avoid multiline ?:, use if.

Use parentheses when calling methods with arguments.

Use {...} when defining blocks on one line. Use do...end for multiline blocks.

Avoid return where not required.

Use return when returning a variable

Avoid line continuation () where not required.

Use ||= freely.

Use OO regexps, and avoid =~ $0-9, $~, $` and $' when possible.

Naming:

Use snake_case for methods.

Use CamelCase for classes and modules. (Keep acronyms like HTTP, RFC, XML uppercase.)

Use SCREAMING_SNAKE_CASE for other constants.

Do not use single letter variable names. Avoid uncommunicative names.

Use consistent variable names. Try to keep the variable names close to the object class name.

Use names prefixed with _ for unused variables.

Do not use inject in library code. In app code it is ok.

When defining binary operators, name the argument "other".

Prefer detect over find, select over find_all.

Comments:

Comments longer than a word are capitalized and use punctuation. Use one space after periods.

Avoid superfluous comments.

The rest:

Avoid hashes-as-optional-parameters. Does the method do too much?

Avoid long methods.

Avoid long parameter lists.

Use def self.method to define singleton methods.

Avoid alias when alias_method will do.

Always freeze objects assigned to constants.

Use OptionParser for parsing complex command line options and ruby -s for trivial command line options.

Write for 1.9, but avoid doing things you know that will break in 1.8.

Avoid needless metaprogramming.

Only give a method one purpose for existing. If you pass in a boolean to a method, what you're saying is that this method has two different behaviours. Just split it into two single purpose methods. If you have to use the words "AND" or "OR" to describe what the method does it probably does too much.

If sections of a method are logically separate by blank lines, then that's probably a sign that those sections should be split into separate methods.

Try to keep methods at no more than 10 lines long, and preferably 5 or less.

General:

Try to have methods either return the state of the object and have no side effects, or return self and have side effects. This is otherwise known as Command-query separation (CQS): Command-query separation - Wikipedia, the free encyclopedia

Do not mutate arguments unless that is the purpose of the method.

Do not mess around in core classes when writing libraries.

Do not program defensively. (See Programming Rules.)

Keep the code simple.

Don't overdesign.

Don't underdesign.

Avoid bugs.

Read other style guides and apply the parts that don't dissent with this list.

Be consistent.

Use common sense.

[flashpixx]

In der Beschreibung sind auch einige interessante Punkte drin, jetzt ist nur die Frage, wie man das technisch umsetzt, so dass man flexibel ist bei den Rules.

Aktuell arbeite ich mit Scons, so dass man einen entsprechenden Builder implementieren kann. Die Frage ist, wie man die Regeln zur Prüfung definiert. Ich hätte da gerne etwas abstraktes. Es gibt für den Google Style ein fertiges Python Script unter https://code.google.com/p/google-styleguide/ was aber eben nur den Google Style prüft

Bearbeitet 2. Januar 2013 von flashpixx

[Pixie]

Hast Du dafür eine Quelle? So etwas klingt sehr gut.

[...]

D.h. ich bräuchte eine schnell zu konfigurierende technische Möglichkeit.

ReSharper :: Features

Ein PlugIn dazu ist StyleCop (ReSharper :: Plug-ins)

Mglw. musst Du nicht das Rad komplett neu erfinden, sondern kannst diverse Tools zur Codeanalyse einbinden.

Die dotnetpro hatte das Thema Software-, Code-Qualität, Metriken etc in einer Ausgabe als Titelthema:

dotnetpro 09/2010

Ist zwar alles sehr .NET lastig, aber vielleicht liefert es einige Inspirationen, die Du verwenden kannst.

[flashpixx]

Da ich Scons (Python) als Buildsystem nutze, habe ich mir CLang (mit LLVM) und den dazugehörigen Python Bindings installiert, damit kann ich dann die C++ Code parsen und direkt in Scons verarbeiten, z.B. kann ich Namespaces, Klassen, Methoden, Variablen extrahieren, da ich direkt auf den AST (abstract syntax tree) zugreifen kann.

[Ulfmann]

Was ich zu diesem Thema auch unbedingt noch nennen möchte ist Code Climate, ein Webservice, der auf Basis von bestimmten Kriterien und Metriken die Qualität von Code bewertet. Um es vorweg zu nehmen, arbeitet dieses Tool nur mit Ruby Code und Repositories auf Github, aber ich bin sicher, dass sich ähnliche Tools für andere Sprachen und Versionsverwaltungen finden lassen.

Für uns ist der Report jedenfalls sehr nützlich, weil man sehr schnell (nach dem Einchecken vom Master Branch) sieht, wo Bedarf an Refactoring besteht. Meistens kann auf diese Weise sehr angenehm duplizierter Code entfernt oder zu komplex gewordene Models umgebaut werden.