Der “CRAP Index” ist eine junge Code-Metrik die versucht nah am Wortschatz und an den Gedankengängen von Entwicklern zu sein. Man könnte auch sagen: “Der WTF-Faktor einer Funktion”.

Die meisten von euch werden einfache Metriken wie die “LOC, Codezeilen” und die “ELOC, Ausführbare Codezeilen” kennen. Treue Leser des Blogs kennen vielleicht auch die “Zyklomatische Komplexität, Anzahl der Verzweigungen in einer Funktion” und die “NPath Complexity, Anzahl der Ausführungspfade durch eine Funktion”. Diese altgedienten Metriken leisten bei der QS gute Dienste sind aber etwas abstrakt. “Die Zyklomatische Komplexität des Codes den du gerade commited hast ist ziemlich hoch” ist ein Satz den man seltener hören wird als, mal ganz unverblümt kommuniziert, “was für ein unverständlicher Mist ist das denn”.

Die CRAP Metrik, übrigens mit dem lange nicht so nett klingenden “Change Risk Analysis and Predictions” ausgeschrieben, kommt aus der Javawelt und wurde vor etwa drei Jahren mit Crap4j jedem einfach zugänglich. Für uns PHPler wird diese Metrik mit dem bevorstehenden Release von PHPUnit 3.5 interessant da sie im neuen “Code Coverage Report” für jede Funktion mit aufgelistet wird. Eine Beta Version bzw. RC1 ist schon einige Zeit verfügbar.

Die Berechnung des CRAP Index ist realtiv trivial und zeigt auch gleich auf wieso wir dafür PHPUnit, bzw. Unittests im allgemeinen, brauchen:

Der Crap Index einer Funktion (f) berechnet sich aus der Zyklomatische Komplexität / “Cyclomatic Complexity” (comp), und der Code Coverage (cc) der Funktion, also dem prozentualen Anteil der Codezeilen die von unseren Unittests durchlaufen werden.

Die Formel sieht nicht trivial aus aber wird hoffentlich durch das folgende Bild deutlich greifbarer.

CRAP-Index(f) = comp(f)^2 * (1 – cc(f)/100)^3 + comp(f)

Auf der X-Achse ist die Code Coverage von 100 bis 0 Prozent, auf der Y-Achse die Zyklomatische Komplexität von 1 bis 30. Mit der Grafik wird, hoffentlich, schnell deutlich das eine Funktion umso besser bewertet wird je einfacher sie ist und je ausführlicher getestet. Der Schwellenwert für “This is Crap” ist hier mit 30 gewählt, aber das soll nur eine Richtlinie sein. Um eine bessere, d.h. niedrige, Bewertung zu erreichen kann man also entweder die Komplexität einer Funktion reduzieren oder sie besser Testen. Gerade beim Implementieren von Algorithmen wird man hier nicht “gezwungen” eine Funktion ggf. unsinniger weiße aufzuteilen sonst kann sie durch Tests “akzeptabel” machen.

Mit dieser Zahl kann man also einfach(er) Aussagen über die Verständlichkeit und Wartbarkeit von Code treffen. Ein einfacher “getter” oder “setter” wird selbst wenn er garnicht getestet ist ziemlich verständlich sein. Es ist nicht sonderlich schwer ihn zu warten. Eine halbwegs komplexe Funktion wird ohne Tests schnell über den Schwellenwert geraten und Änderungen sind dort auch nicht mehr einfach durchzuführen. Gibt es allerdings einige Tests, so was wir uns beim Refactoren darauf verlassen können nichts Kaput zu machen, ist auch der CRAP-Index unter dem Schwellenwert. Funktionen die eine Zyklomatische Komplexität von 30 oder mehr haben können wir allerdings auch mit noch so guter Code Coverage nicht mehr “retten”, sie sind oftmals zu komplex und gut wartbar zu sein.

Wenn also morgen euer Kollege zu euch kommt und sagt “Dein Code ist ganz schön CRAPpy” wisst ihr jetzt was gemeint ist.

Für solche Probleme gibt es oft verschiedene Ursachen. Um solche Probleme zu vermeiden, sollte man sich natürlich Gedanken um einen ordentlichen Deployment-Prozess machen, mit dem man schnell wieder auf einen funktionierenden Stand zurückspringen kann. Viele solcher Probleme rühren aber oft daher, dass eine Integration nicht ordentlich getestet werden konnte oder manche Probleme auch einfach erst mit einer Datenbasis auftreten, wie sie höchstens das Produktivsystem, nicht aber das Entwicklungssystem hat.

Zur Vermeidung solcher Probleme empfehlen sich Staging Systeme. Ein Staging System beschreibt eine Serverinstanz, welche mit der Umgebung des Produktivsystems möglichst identisch sein sollte, im Optimalfall also auch die gleiche Hardware. Das ist natürlich in den meisten Teams oder Projekten eine recht utopische Vorstellung, daher muss es nicht zwingend eine eigene Hardwarelösung sein. Ein virtueller Server macht hier ebenfalls einen ausreichenden Job.

Aber fangen wir von vorne an. Welche Aspekte sind denn für ein sinnvolles Staging System wichtig? Auf jeden Fall sollten Staging-und Produktivsystem die gleiche Softwareplatform haben. Das bedeutet es sollte in jedem Fall das gleiche Betriebssystem in der gleichen Version laufen, alle verwendeten Softwarepakete (PHP, Datenbankserver usw) sollten zwingend in der gleichen Version installiert sein und es sollte auch der gleiche Umfang an Software installiert sein, in einer möglichst identischen Konfiguration. Natürlich lassen sich gewisse Abweichungen in der Konfiguration nicht vermeiden. Wenn wir etwa auf unserem Produktivsystem auf Grund des verfügbaren RAM höhere Speicherlimits haben, als auf dem Staging System, dann ist das eben nicht zu vermeiden, stellt insofern kein aber Problem dar, weil weniger Speicher für den Testfall ja durchaus von Vorteil sein kann, um früher Probleme beim Speicherverbrauch aufzudecken. In jedem Fall sollte man allerdings davon absehen, das Staging System als VHost auf dem Produktivserver laufen zu lassen. Zum Beispiel würden somit jegliche Tests an der Konfiguration des VHosts des Staging Systems, die einen Neustart der Serverdienste benötigen, auch das Produktivsystem beeinflussen.

Die Applikation, die wir deployen, sollte ferner natürlich ebenfalls möglichst identisch konfiguriert sein. Die Quelldateien sollten beide auf dem gleichen Stand und aus dem gleichen Branch stammen. Auf dem Staging System dürfen sich ausschließlich nur die Änderungen befinden, die auch tatsächlich integriert wurden und live gehen sollen.

Ein spannender Punkt ist letztlich dann noch die Datenbank und die damit verbundene Datenbasis. Das Ziel eines Staging Systems ist es natürlich immer möglichst identisch an das Produktivsystem heranzukommen, das gilt also auch für die Datenbasis. Auf Grund der eingeschränkten Platzverhältnisse auf einem Staging System ist das aber oft nicht realistisch machbar. Selbst wenn wir die gesamte Datenbank spiegeln können, haben wir damit ja immer noch nicht zwingend auch alle restlichen Daten auf dem Staging System verfügbar, wie etwa Useruploads etc.

Hier muss man genauer prüfen und von Projekt zu Projekt entscheiden. Je nach System empfiehlt es sich die gesamten Datenstämme gewisser Nutzergruppen zu kopieren, mit denen man etwa arbeiten möchte. Es müssen also nicht zwingend alle Daten für alle Nutzer sein, aber man sollte sicherstellen, dass man zumindest aus gewissen Nutzergruppen verschiedene Testfälle abdecken kann.

Für das “Überschreiben” der Daten auf dem Staging Server durch aktuelle Daten vom Produktivsystem ist es ratsam, ein Script zu schreiben. Das hat den einfachen Hintergrund, dass man so auch “auf Knopfdruck” schnell und einfach auf dem Staging System eine aktuelle Datenbasis erhält, mit der man etwa auch Probleme reproduzieren kann, die vielleicht erst auf dem Produktivsystem aufgetreten sind. Dieses Script ist im Optimalfall parametrisiert, sodass man bequem wählen kann, in welchem Umfang und aus welchem Bereich Daten kopiert werden sollen. Das ist natürlich ebenfalls stark Projektabhängig und man muss dafür das System und seine Abhängikeiten gut kennen.

Zuletzt sollte das Staging System natürlich in den Deploymentprozess eingebunden sein. Es dürfen etwa keine Änderungen auf das Produktivsystem gehen, ohne vorher im vollen Umfang der Integration auf dem Staging System getestet worden zu sein. Ferner sollte man etwa eine Abnahme durch den Product Owner in einem SCRUM Team ausschließlich auf dem Staging System machen und nicht an irgendwelchen Entwicklerbuilds, die nicht vollständig integriert sind etc.

Das war mal soweit ein kleiner Überblick darüber, was Staging System so mit sich bringen sollte und worauf geachtet werden sollte. Das alles sind mehr ein paar allgemein gehaltene Ratschläge, denn wie so vieles in der Softwareentwicklung, ist der Einsatz verschiedener Mittel nie “einfach so” möglich, sondern stark abhängig von der Umgebung. Generell bieten Staging Systeme aber einige Vorteile. Ganz davon abgesehen, dass sie helfen eine fehlerhafte Integration zu vermeiden und Probleme vor dem Aufschlagen auf dem Produktivsystem aufzudecken. Sie sind noch dazu eine große Hilfe, wenn auf dem Produktivsystem Probleme auftreten, die sich auf dem Entwicklersystem nicht reproduzieren lassen. Wenn man die Möglichkeit hat, sich ohne weiteres seine Datenbasis auf das Staging System zu spiegel, um dort zu testen, spart das oft viel Zeit und damit auch Geld.

Nils hat sich vor längerer Zeit schon einmal mit Kommentaren direkt im Quellcode beschäftigt und damit wie man sie durch bessere Methodennamen vermeiden kann. Außerdem gib es im PHP-Magazin einen sehr schönen Artikel zum Kommentar-Smell.

Meine Argumentationsgrundlage soll hier “Zeit” sein. Sourcecode wir öfter gelesen als geschrieben und sollte so geschrieben werden, dass er schnell erfassbar und verständlich ist. Deswegen einigen wir uns für Projekte auf Coding-Standards und nehmen uns – meistens/hoffentlich – Zeit dafür Methoden aussagekräftig zu benennen.

Etwas Beispielcode der gerne auch mal mit dem Satz “Ihr habt gesagt ich soll alles dokumentieren !” einhergeht und mir physischen Schmerz bereitet.

<?php

class meineKlasse {

    /**
     * Konstruktur
     */
    public function __construct() {
    }

    // ... Methoden der Klasse

}

Dieser Code ist auf mindestens zwei Ebenen verstörend.

Der Kommentar absolut überflüssig. Er beinhaltet keinerlei Information und hilft niemandem der auch nur ein kleiner bischen PHP kann weiter. Das Einzige das er erreicht ist, dass jeder der die Klasse öffnet ihn ggf. kurz überfliegt und damit Zeit verschwendet.

Wie wäre es mit “Erstellt eine Instanz von meineKlasse” ?

Das wäre noch schlimmer, mehr Wörter, mehr Zeit, immer noch keine Information und beim umbenennen der Klasse müsste man ihn auch noch anpassen.

Ich finde hier kann man sich den kompletten DocBlock sparen. Wenn ihr euch in eurem Projekt darauf geeinigt habt, dass alles einen DocBlock hat, würde ich vorschlagen den einfach leer zu lassen. Wenn das auch nicht erlaubt ist würde ich sehr gerne von euch hören wieso und euch ggf. empfehlen diese Regel zu ändern. Es nützt nichts Entwickler damit zu beschäftigen Trivialitäten niederzuschreiben, es senkt meiner Erfahrung nach sogar die Qualität der restlichen Dokumentation wenn die Leute mit einer “muss irgendwas über alles schreiben damit der Code Sniffer zufrieden ist” Mentalität an die Sache herangehen, ob bewusst oder unbewusst.

Der einfachste Weg hier die Problematik zu umgehen ist aber den Konstruktor einfach komplett zu löschen.  Er erfüllt im Moment keine Funktion ! Er ist sogar mögliche Fehlerquelle da er den “parent” Konstruktor nicht aufruft, etwas das automatisch geschieht wenn diese 5 Codezeilen gelöscht würden. Solche leeren Konstruktoren kommen meistens daher, dass sie in einem Klassentemplate existieren und an den Stellen an denen sie nicht gebraucht werden nicht gelöscht werden.

Also spart Zeit und erhöht die “Information pro Bildschirmseite” wo es sinnvoll ist. Eurer zukünftiges Ich wird es euch danken.