Clean Coding - Theorie und Praxis Guide (in german)

Clean CodingTheorie & Praxis GuideArtem Kaftanenko

13.05.2011 Clean Coding - Theory & Praxis Guide 1

Agenda


Agenda

Part I - Theorie

Einführung

Motivation und Ziele

Namensgebung

Funktionen

Klassen

Ausblick

Part II - Praxis Guide


Part I - Theorie

Einführung

Bjarne Stroustrup… inventor of C++ and author of The C++ Programming Language

I like my code to be elegant and efficient.

The logic should be straightforward to make it hard for bugs to hide, the dependencies minimal to ease maintenance, error handling complete according to an articulated strategy, and performance close to optimal so as not to tempt people to make the code messy with unprincipled optimizations.

Clean code does one thing well.


Theorie

Einführung

http://www.b-s-s.de/


Theorie

Einführung

Grady Booch… author of Object Oriented Analysis and Design with Applications

Clean code is simple and direct. Clean code reads like well-written prose. Clean code never obscures the designer’s intent but rather is full of crisp abstractions and straightforward lines of control.



Theorie

Einführung

“Big” Dave Thomas... godfather of the Eclipse strategy

Clean code can be read, and enhanced by a developer other than its original author. It has unit and acceptance tests. It has meaningful names. It provides one way rather than many ways for doing one thing. It has minimal dependencies, which are explicitly defined, and provides a clear and minimal API. ...



Theorie

Einführung

Dirty Code

„natürlich“ entstandene Code

gefährdet

Langlebigkeit eines SW-Produktes

seine Stabilität und Erweiterbarkeit

Clean Coding legt besonders Acht auf

Lesbarkeit

Nebeneffektfreiheit

Isolierung der Systemänderungen

---


Theorie

"Softwareentwicklung braucht Profis. Was aber sind Profis? Menschen die mit der Softwareentwicklung Geld verdienen? Nein, ..., es gehört mehr und anderes dazu. Professionalität in der Softwareentwicklung hat nichts mit Geld zu tun. Sie hat auch nur bedingt mit einem bestimmten Ausbildungsweg zu tun.

<Es gibt> ... professionelle Softwareentwickler, die wenig oder gar kein Geld mit ihrer Software verdienen und <es gibt> ... professionelle Softwareentwickler, die weder Diplom noch Doktortitel haben.„

http://clean-code-developer.de (Stand: 10.05.2011)

Einführung


Theorie

[MR09] Clean Code: A Handbook of Agile Software Craftsmanship; Robert C. Martin (aka Uncle Bob) ISBN-13: 978-0132350884

Einführung - Informationsquellen

[CCD] Clean Code Developer – Initiative von Ralf Westphal und Stefan Lieser


Part I - Theorie

Motivation & Ziele


Theorie - Motivation & Ziele

Ziel - Mehrwert (1)

Kunde

Implementierung = Wunsch (im Endeffekt) Kosten der Änderungswünsche realistisch abschätzbar

Endbenutzer

deutlich weniger Bugs schnellere Bug-Beseitigung

Projektleiter (PL)

realistisch abschätzbare Impl.-/Änderungsaufwände höheres Vertrauensniveau an die Entwicklung



Ziel - Mehrwert (2)

Softwarearchitekt (SWA)

sauberes und überschaubares Design auch auf Impl.-Niveau leicht kontrollierbares Qualitätsniveau motiviert reguläre Aktualisierung der Style-Guides Implementierung mit den Anforderungen (leicht) abgleichbar

Entwickler

schneller Einstieg leichte Nachvollziehbarkeit des Fremdcodes Lerneffekt ebenfalls sauber zu programmieren gutes Gefühl sich stolz als einen Professional bezeichnen zu dürfen



… und den Preis

Mehrkosten? => franglich, aber eher so gut wie keine + langfristige Spareffekte

der einzige Unterschied: natürliches/ungeübtes vs. systematisches Vorgehen

meidet Kreativitätskrisen (bei SWA’s/Entwickler)

leicht gemachter fachlicher Einstieg für die Neueinsteiger

Synergieeffekte durch etwa gleichen Gedankenfluss/Vorgehensweise

schafft Grundlage für das rechtzeitige Refactoring, bewahrt Code-Consistence


Theorie

Namensgebung


Theorie - Namensgebung

…

Charakteristik guter Namen

aussagekräftig aussprechbar auffindbar (IDE) eindeutig & klar

Auswahl der Schlüsselwörter

ein Wort per Konzept aus der Domainsprache

=> (Problem/Lösungs-Domain) Verwenden von Namenskonventionen

=> z. Bsp. für Funktionen: is<…>, set<…>, get<…>, …



…

Prinzipien

Mehrdeutigkeit vermeiden

Desinformationen vermeiden=> „say what you mean, mean what you say.“

aussagekräftigen Kontext verwenden=> meist durch gut benannte Klassen, Funktionen und andere Namensräume gegeben=> wenn kein klarer Kontext gegeben, muss dieser ein Teil des Namens sein

Verwendung desselben Schlüsselworts für mehrere Konzepte vermeiden

Typ/Scope/Mitgliedschaft bedingte Präfixe vermeiden



…

Gute Namen zu finden ist schwierig, aber

zahlt sich sehr schnell aus

animiert zur Suche nach einem Konsensus

schafft gemeinsame Basis für alle Entwickler

trägt der inkrementeller Entstehung von DSL bei


Theorie

Funktionen


Theorie - Funktionen

Einführung (1)

FUNCTION … SHOULD DO ONE THING.

… SHOULD DO IT WELL.… SHOULD DO IT ONLY.

Diese Beschreibung

bestimmt die Größe der Funktion sichert ihre Nebeneffekt-Freiheit weist auf die Auswahl der Funktionsnamen hin



Einführung (2)

Funktionsgröße

Regel 1: … muss KLEIN seinRegel 2: … muss noch KLEINER sein

Funktionsname

… soll deskriptiv sein… soll beschreiben WAS die Funktion tut… soll beschreiben ALLES was die Funktion tut

Eine Funktion ist sauber wenn:

… implementiert nur eine einzige Handlung… implementiert Handlung nur eines Abstraktionsniveaus… ihre Funktionalität ist durch Funktionsnamen vollständig beschrieben

=> Nebeneffekt-Freiheit



Logikfluss

Als Ergebnis

viele kurze Funktionen (3-10 Zeilen) nicht selten eine Funktion nur von einer einzigen Stelle aufgerufen

„Step-Down“-Regel

aufzurufende nach den aufrufenden Funktionen (vertikale Anordnung)

Gruppierung der Funktionen

die einander aufrufen die ähnliche Funktionalität umsetzen die die gleichen Objekte/Instanzvariablen behandeln

sich wiederholende Switch-Anweisungen

meist durch Polymorphie lösbar



Benennung

Muss ein Verb enthalten

Namenskonventionen wichtig

dieselben Verben für dieselben Handlungen=> Bsp.: get, set, is, find, query, check, …

Schlüsselwörter aus den Domainsprachen

… sonst der allgemeinen Regeln der Namensgebung folgen (s. oben)



Argumente (1)

Argumentanzahl

keine Argumente

ist ideal => ganzen Zustand durch Instanzvariablen bestimmt

ein Argument

… prüft Annahmen=> Rückgabe: boolesche Typ boolean fileExists(“MyFile”)

… behandelt Ereignisse=> keine Rückgabe void onDataLoad(Event event)

… transformiert dieses Argument/Objekt=> Rückgabe: transformiertes Objekt InputStream fileOpen(“MyFile”)


Argumentenanzahl

zwei Argumente

assertEquals(expected, actual)=> leicht zu verwechselnde Reihenfolge gleichartiger Argumenten

p = new Point(0,0); => sind geordnete Bestandteile desselben Wert-Objekts!

drei Argumente

assertEquals(message, expected, actual)=> leicht zu verwechselnde Reihenfolge gleichartiger Argumenten

assertEquals(1.0, amount, .001)=> sind fachlich bedingt (Vergleich von zwei Floatpoint-Werten ist nur mit

einem Genauigkeitsgrad möglich)


Argumente (2)



Argumente (3)

Argumentenanzahl

mehr als drei Argumente

eindeutiges Warnsignal zum Refactoren

Mittel zur Reduzierung der Argumentenanzahl:

… in Instanzvariablen umwandeln … in Wrapper-Klassen kapseln… Funktion in Kontext eines der Argumente verschieben

<some-class>.writeField(outputStream, name) => outputStream.writeField(name)



Argumente (4)

Argumentarten

Flag-Argumente (boolesche)=> verletzt „do one thing“-Regel

in/out Argumente=> Nebeneffekte=> verschlechtern Nachvollziehbarkeit

Argument-Listen=> wenn diese gleich behandelt werden = ein Argument vom List-Typ=> im übrigen dieselben Begrenzungen auf die Argumentenanzahl



Fehlerbehandlung

Exception werfen bevorzugt über Rückgabe eines ErrorCode‘s

Fehlerbehandlung = one thing=> in die Extrafunktion auslagern

… sonst ist dies das Thema für eine Extrapräsentation.


Theorie

Klassen


Theorie - Klassen

Einführung

… es gibt eine gewisse Korrelation mit den Anforderungen zu den Funktionen

Klassengröße

Regel 1: … muss KLEIN seinRegel 2: … muss noch, Ihr wisst schon, KLEINER sein

Klassenname

… soll deskriptiv sein… soll beschreiben WOFÜR die Klasse verantwortlich ist… soll beschreiben ALLES WOFÜR die Klasse verantwortlich ist


Theorie - Klassen

Klassenorganisation – Responsibility-Merkmal

Single Responsibility Principle (SRP)

public class SuperDashboard extends JFrame implements MetaDataUserpublic String getCustomizerLanguagePath()public void setSystemConfigPath(String systemConfigPath)public String getSystemConfigDocument()public void setSystemConfigDocument(String systemConfigDocument)public boolean getGuruState()public boolean getNoviceState()public boolean getOpenSourceState()public void showObject(MetaObject object)public void showProgress(String s)public void setIsMetadataDirty(boolean isMetadataDirty)public Component getLastFocusedComponent()public void setLastFocused(Component lastFocused)public void setMouseSelectState(boolean isMouseSelected)public boolean isMouseSelected()public LanguageManager getLanguageManager()public Project getProject()public Project getFirstProject()public Project getLastProject()public String getNewProjectName()public void setComponentSizes(Dimension dim)public String getCurrentDir()public void setCurrentDir(String newDir)public void updateStatus(int dotPos, int markPos)public Class[] getDataBaseClasses()public MetadataFeeder getMetadataFeeder()public void addProject(Project project)public boolean setCurrentProject(Project project)


Theorie - Klassen




public class SuperDashboard extends JFrame {public Component getLastFocusedComponent()public void setLastFocused(Component lastFocused)public int getMajorVersionNumber()public int getMinorVersionNumber()public int getBuildNumber()

}


Theorie - Klassen




public class SuperDashboard extends JFrame {public Component getLastFocusedComponent()public void setLastFocused(Component lastFocused)public int getMajorVersionNumber()public int getMinorVersionNumber()public int getBuildNumber()

}public class Version {

public int getMajorVersionNumber()public int getMinorVersionNumber()public int getBuildNumber()

}


Theorie - Klassen

Klassenorganisation – Kohäsion-Merkmal

Clean-Code-Anforderung zu den Funktionen – Minimierung der Argumentenanzahl

als Folge – viele kleinere Funktionender ganze Objektzustand ist durch seine Instanzvariablen präsentiert

Wenn eine Untermenge der Instanzvariablen ausschließlich von einer Untermenge der Klassenmethoden benutzt wird => Warnsignal zur Klassen-Spaltung


Theorie - Klassen

Klassenorganisation – Änderungsrisiko-Merkmal

Moderne SW-Systeme sind permanenten Änderungen unterworfen

Änderung eines Systemteils => Systemrest funktioniert nicht mehr als erwartet

Aus diesem Grund sollte man das System so organisieren, damit die Funktionalität der nicht angefassten Systemteile erhalten bleibt


Theorie

Ausblick


Theorie - Ausblick

Formatierungsregeln

Kommentare

Unit Tests

Concurrency

Error-Handling

Systemaufbau

…

Weitere hier nicht behandelte Themen


Theorie - Ausblick

Heuristiken - Beispiele (1)

Comments

C1: Inappropriate InformationC2: Obsolete CommentC3: Redundant CommentC4: Poorly Written CommentC5: Commented-Out Code

Environment

E1: Build Requires More Than One StepE2: Tests Require More Than One Step

Functions

F1: Too Many ArgumentsF2: Output ArgumentsF3: Flag Arguments F4: Dead Function


Theorie - Ausblick

Heuristiken - Beispiele (2)

General

G1: Multiple Languages in One Source FileG2: Obvious Behavior Is UnimplementedG3: Incorrect Behavior at the Boundaries G4: Overridden SafetiesG5: DuplicationG6: Code at Wrong Level of AbstractionG7: Base Classes Depending on Their Derivatives...

… und viele anderen sind im [MR09] zu finden.


PART II – Praxis Guide


Praxis Guide

Aufgabenstellung

Ausgangsdaten für die Entwickler

Fachliche Spezifikation des zu realisierenden Systems

durch Fachabteilung/Analysten erarbeitet

mittels Dekomposition des Gesamtsystems in

Fachbereiche/Fachklassen fachliche Abhängigkeiten/Operationen

Aufgabe des Entwicklers

Umsetzung dieser Spezifikation


Praxis Guide

Fachliche Abstraktionsniveau

Businesslogik (BL) Schnittstelle

spiegelt die Fachspezifikation auf die Implementierungssprache

… um Implementierung mit der Spezifikation abgleichbar zu halten=> Verwendung einer fachlichen DSL nötig

muss beschreiben WAS implementiert werden muss

=> Strukturierungseinheiten: Aggregate, Fachklassen, …=> nächste Hierarchiestufe: Businessoperationen

Businesslogik Implementierung

muss das WIE beschreiben, aber immerhin im Scope des BL-Abstraktionsniveaus

evtl. zwischen mehreren Aggregaten teilbaren lower-level BL-Framework

immerhin Realisierung in den Begriffen einer fachlichen DSL


Praxis Guide

Technische Abstraktionsniveau

Frameworks

commons Datenpersistenz Dependency Injection …

(Kommunikations-) Schnittstellen zu anderen Systemen

JMS FTP Email …


Praxis Guide

Clean Coding – Verfahren (1)

Inkrementelle Verbesserung des Codes, rechtzeitigen Reviews/Refactorings

Einhaltung der Grenzen einzelner Abstraktionsebenen

auf Schnittstellen-Niveau innerhalb der Implementierung einzelner Funktionen

Passende Benennung der Artefakte

Pakete/Module Klassen Funktionen und ihre Argumente Instanz- bzw. lokale Variablen …

Eindeutiger Kontext


Praxis Guide

Clean Coding – Verfahren (2)

Suche nach passender Benennung führt zu richtigen Designentscheidungen

Pakete/Klassen/Funktionen/… (Kontexte)

zu spezialisieren bzw. zu generalisieren

zu spalten bzw. in anderen Kontext auszulagern

die Artefakte ähnlicher Abstraktionsniveau/Funktionalität landen in den naheliegenden/denselben Kontexten und werden sogar oft ähnlich/gleich benannt

erleichtert Identifikation der Artefakte mit gleicher/ähnlicher Funktionalität

ermöglicht beste Implementierung auszuwählen und Redundanzen zu beseitigen


Theorie & Praxis Guide

[MR09] Clean Code: A Handbook of Agile Software Craftsmanship; Robert C. Martin (aka Uncle Bob) ISBN-13: 978-0132350884

Weiterführende Informationen

[CCD] Clean Code Developer – Initiative von Ralf Westphal und Stefan Lieser

Technology

Clean Coding - Theorie und Praxis Guide (in german)