CleanCode Ratgeber (Sprachenübergreifend)
Freut mich das Ihr Interesse habt an meinem Clearcode Ratgeber. Dieser ist Sprachenübergreifend. Zur Simplizität benutze ich hier eine einzige Sprache und habe mich für Powershell entschieden und diesen Ratgeber mit meinem Script zum Dateivergleich => KLICK HIER
ClearCode ist wichtig! Egal ob Ihr der Welt etwas mit eurem Code hinterlasst oder nicht. Auch Ihr könnt mal in den wundervollen Geschmack kommen einen fremden Code zu „entschlüsseln“. Wenn Ihr euch dann mal ohne Bitbucket mit einer schönen Suchfunktion im Code nach einer Funktion sucht die irgendwo mal erwähnt wurde, oder theoretisch verfügbar sein sollte seht ihr das alles etwas anders.
Zudem ist die Art wie man Code schreibt eine Unterschrift für einen Programmierer.
Folgende Punkte sind mir wichtig:
- Deutliche Variablenname (Semantik) damit einhergende
- Eindeutige Kommentare pro Step (Wenigstens ein Einzeiler)
- Trennung durch Anschnittsboxen mit #-Rahmen
- Auslagerung in Funktionen für die Übersicht.
- Zu Beginn des Scripts eine Erklärung durch einen Ablaufplan
- Regelmäßige Rückmeldungen durch Hostausgaben
- Hauptscript kommt immer zuerst (Ratgeber Compiler austricksen => KLICK MICH)
- Optional: Debuggingmodus mit einbauen
- Wichtigste: Eindeutige Einrückungen!!!
Deutliche Variablennamen
Wenn jemand mitten im Script eine Variable findet soll er erkennen können wofür diese ist. Zwar muss man schon ein wenig Hintergrundinfo haben, aber auch so mancher Name kann dann schonmal was länger werden, aber somit ist er immernoch logisch. Folgende Variablen, vorrangeführt mit der Bedeutung per Kommentar, zeige ich mal als Beispiel.
#Feste Pfade von Source und Destiantion
$FIX_SOURCE
$FIX_DESTINATION
#Pfad des Backups/der Backupfiles
$BCKpfad
#Array wird erzeugt mit allen Dateinamen eines Dateityps
$Array_von_YYY_Dateien = Get-ChildItem "$Temppfad\*.*" -Filter "*.YYY"
#Der aktuelle Dateiname aus dem Array heißt z.B. wörtlich "Aktuelle Datei"
foreach ($Aktuelle_YYY_Datei in $Array_von_YYY_Dateien)
Eindeutige Kommentare pro Step (Wenigstens ein Einzeiler)
Gewisse Programmteile sind es wert zu kommentieren. So weiß man z.B. was man mit einer Zeile erzeugen oder erledigen wollte. Evtl. wie letztes Beispiel auch mal einen IF-Zweig genauer beschreiben.
#Bestimmen der Ordnerpfade Backup und Temporärer Arbeitsordner
-----------------------------------------------------------------------------------
#Verschieben von allen WWW/XXX/YYY/ZZZ Dateien zum Backupen und zum verhindern das nachher einiges gedoppelt bearbeitet wird. Verschoben wird in einen Ordner mit Datumsformat YYYY/MM/DD
-----------------------------------------------------------------------------------
#Splitten des Pfades und entfernen von Pfad und Dateierweiterung
-----------------------------------------------------------------------------------
#IF Verzweigung zur Prüfung ob eine auf dem Namenspräfix passende ZZZ Datei vorhanden ist.
#Wenn die gleichnamige ZZZ Datei vorhanden ist verschiebe beide Dateien in den Versandordner.
#Wenn keine gleichnamige ZZZ Datei vorhanden ist verschiebe die YYY Datei in den Singleordner.Trennung durch Abschnittsboxen mit #-Rahmen
Programmabschnitte trenne ich gerne optisch mit Boxen die einen Rahmen aus Rauten haben.
##########################################
## Beginn des eigentlichen Hauptscripts ##
##########################################
-----------------------------------------------------------------------------------
##################################################
# AB HIER SIND KEINE ÄNDERUNGEN MEHR ERORDERLICH #
##################################################
-----------------------------------------------------------------------------------
############################################################################
## Hier steht der Titel des Scripts drin ##
############################################################################
-----------------------------------------------------------------------------------
####################################
## Jetzt wird das Backup erstellt ##
####################################Auslagerung in Funktionen für die Übersicht.
Funktionen sind schön! Sie lassen sich bei Bedarf einfach einklappen. Zudem ist der Aufruf einfach wenn man diese an mehreren Stellen benötigt.
function Prüfungsschleife-XXX {...}
function Auswertung_starten {...}
function Hauptscript {...}Zu Beginn des Scripts eine Erklärung durch einen Ablaufplan
Es ist wichtig zu wissen was ein Script eigentlich erledigen soll. So ist es am einfachsten am Anfang des Scripts das eigentliche To-Do aufzuschreiben damit man es sowohl bei der Programmierungsphase als auch nach einiger Zeit wenn man z.B. Änderungen vornehmen soll , noch weiß welchen Ablauf das Script genau hat.
#####################################################################################################################
# 1. Backup Ordner mit TimeStamp wird erstellt #
# 2. Alle Dateien werden in den Backup Ordner verschoben #
# 3. Temp Ordner wird in Backup Ordner erstellt #
# 4. Alle Dateien des Backup Ordners werden in den Temp Ordner kopiert #
# 5. Skript erstellt Array aus vorhanden WWW Dateien #
# 6. Pro Eintrag im Array: #
# a. Ziehe Basisname aus WWW Datei (Ohne Dateierweiterung) #
# b. Suche nach passender ZZZ Datei (Prüfung auf Namenskonvention) #
# c. IF-Zweig: #
# i. Datei vorhanden: verschiebe in Ordner Temppfad/Versand #
# ii. Datei nicht vorhanden: verschiebe WWW in Ordner Temppfad/Fehler #
# 7. Wiederhole Vorgang für alle weiteren Dateien ebenso für ZZZ (zum verschieben in Fehler) #
# 8. Starte Auswertung und erfasse alle Dateien in Temppfad/Fehler in einer TXT-Datei #
# 9. Verschiebe alle Dateien von Temp-Fehler/Versand in Produktiv Fehler/Versand #
##################################################################################################################### Regelmäßige Rückmeldungen durch Hostausgaben
Diese sind wichtig wenn man z.B. im Programmierzeitraum regelmäßig tests machen möchte und bekommt so Rückmeldungen von Variablen und deren Inhalt. Hilfreich wenn z.B. mal ein Falscher Wert ausgegeben wird oder eine Aktion wegen einer Pfad-Variable nicht ausgelöst wird.
Write-Host -BackGroundColor Green "Der Pfad $($FIX_DESTINATION) existiert."
write-host "Backup wird erstellt"
Write-Host "Aktuelle YYY-Datei $SingelDateiName"
Write-Host "Versandbereites Datenpaar gefunden $Datei_als_YYY wird verschoben"
Write-Host "Hauptscript wird gestartet"Hauptscript kommt immer zuerst (Ratgeber Compiler austricksen)
Tja! Der Compiler ist so ein Ding… Muss erstmal alles gesehen haben um zu wissen das es existiert. Jede Funktion muss er passiert haben bevor er Sie aufrufen kann. Hierzu dann aber mehr im extra Ratgeber und dort auch wieso ich das Hauptscript immer als Funktion verpacke.
Optional: Debuggingmodus mit einbauen
Ein Debuggingmodus ist interessant wenn man ein Script hat das den Log nicht vollklatschen soll. So habe ich während der Programmierung ein Script mit allen möglichen Ausgaben. Sozusagen das All-Inclusive Paket. Das soll aber später nicht alles geloggt werden. Hierzu habe ich dann die Silent-Variante.
Dies wird Hardcoded einfach mit einer Variable und einer Scriptallumfassenden IF-Abfrage realisiert. Gibt es natürlich auch in schöner aber so mache ich am Ende einfach Copy-Paste und entferne alle Write-Host Einträge. In meinem Beispielbezogenen Script ist dieser nicht vorhanden aber dafür im Installationsscript => KLICK HIER
#Erste Zeile
$debuggingmodus=1
if ($debuggingmodus-eq '1')
{
#HIER IST DAS SCRIPT MIT DEBUGGINGAUSGABEN
}else
{
#HIER IST DAS SCRIPT OHNE DEBUGGINGAUSGABEN
}Wichtigste: Eindeutige Einrückungen!!!
Ohne Einrückungen ist ein Code, der nunmal aus einzelnen Zeilen mit unterschiedlichen Bezügen zueinander, besteht so schwer zu lesen wie ein Roman der keine Leerzeichen beinhaltet. Für mich ist es eins der Essentiellsten Dinge im Code. Das Einrücken und die Absätze helfen z.B. zu erkennen wo eine Schleife oder eine IF-Anweisung endet. Umso verschachtelter ein Code ist umso schwerer wird es. Genauso ist es mit HTML Dokumente oder CSS Dateien die einzilig geschrieben wurden, weil sie z.B. maschinell erstellt wurden.
Nehmen wir mal als Beispiel eine mehrfache IF-Anweisungen mit Schleife und Funktionsaufruf (der Code ergibt keinen Sinn!)
#Mit Formatierung
$debuggingmodus=1
function Prüfungsschleife{
#Splitten des Pfades und entfernen von Pfad und Dateierweiterung
$SingelDateiName = (Get-Item "$Aktuelle_Datei").Basename
Write-Host "Aktuelle Datei $SingelDateiName"
#Setzen von Variablen zur weiteren verarbeitung
$Datei_als_Datei = "$Temppfad/$SingelDateiName.ENDUNG"
$Datei_als_Zweite_Datei = "$Temppfad/$SingelDateiName.ENDUNG"
#IF Verzweigung zur Prüfung ob eine auf dem Namenspräfix passende Datei Datei vorhanden ist.
#Wenn die gleichnamige Zweite Datei vorhanden ist verschiebe beide Dateien in den Versandordner.
#Wenn keine gleichnamige Zweite Datei vorhanden ist verschiebe die Datei Datei in den Singleordner.
If ( Test-Path "$Datei_als_Datei")
{
# IF ZWEIG => Zweite Datei ist vorhanden
Write-Host "Versandbereites Datenpaar gefunden $Datei_als_Datei wird verschoben"
Write-Host "Versandbereites Datenpaar gefunden $Datei_als_zweite_Datei wird verschoben"
Move-Item "$Datei_als_Datei" "$Aussortierte_Paare"
Move-Item "$Datei_als_zweite_Datei" "$Aussortierte_Paare"
}else{
# IF ZWEIG => Zweite Datei ist NICHT vorhanden
Write-Host "Keine passende Datei als IDX gefunden! $Aktuelle_XML_Datei wird verschoben"
Move-Item "$Datei_als_xml" "$Aussortierte_Single"
}
}
if ($debuggingmodus-eq '1')
{
#Feste Pfade von Source und Destiantion
$FIX_SOURCE
$FIX_DESTINATION
if ($FIX_SOURCE-eq 'C:\Users\Blabla')
{
#Pfad des Backups/der Backupfiles
$BCKpfad
#Array wird erzeugt mit allen Dateinamen eines Dateityps
$Array_von_YYY_Dateien = Get-ChildItem "$Temppfad\*.*" -Filter "*.YYY"
#Der aktuelle Dateiname aus dem Array heißt z.B. wörtlich "Aktuelle Datei"
foreach ($Aktuelle_YYY_Datei in $Array_von_YYY_Dateien)
}else{
for (2000, 1, i, ++)
}Jetzt wird dem ein oder anderen aufgefallen sein das ich zum Schluss ein paar Fehler eingebaut habe. Es fehlen geschweifte Klammern für die FOREACH-Schleife, ebenso wie die abschließende geschweifte Klammer für die IF-Anweisung. Warum? Weil das hier zwar auch auffallen kann, dies aber wesentlich länger braucht und schwieriger sein wird als den Fehler im ClearCode zu debuggen. Also schauen wir uns doch mal den Code an wenn er unsortiert und ohne Absätze wäre.
#Ohne Formatierung
$debuggingmodus=1
function Prüfungsschleife{
#Splitten des Pfades und entfernen von Pfad und Dateierweiterung
$SingelDateiName = (Get-Item "$Aktuelle_Datei").Basename
Write-Host "Aktuelle Datei $SingelDateiName"
#Setzen von Variablen zur weiteren verarbeitung
$Datei_als_Datei = "$Temppfad/$SingelDateiName.ENDUNG"
$Datei_als_Zweite_Datei = "$Temppfad/$SingelDateiName.ENDUNG"
#IF Verzweigung zur Prüfung ob eine auf dem Namenspräfix passende Datei Datei vorhanden ist.
#Wenn die gleichnamige Zweite Datei vorhanden ist verschiebe beide Dateien in den Versandordner.
#Wenn keine gleichnamige Zweite Datei vorhanden ist verschiebe die Datei Datei in den Singleordner.
If ( Test-Path "$Datei_als_Datei"){
# IF ZWEIG => Zweite Datei ist vorhanden
Write-Host "Versandbereites Datenpaar gefunden $Datei_als_Datei wird verschoben"
Write-Host "Versandbereites Datenpaar gefunden $Datei_als_zweite_Datei wird verschoben"
Move-Item "$Datei_als_Datei" "$Aussortierte_Paare"
Move-Item "$Datei_als_zweite_Datei" "$Aussortierte_Paare"
}else{# IF ZWEIG => Zweite Datei ist NICHT vorhanden
Write-Host "Keine passende Datei als IDX gefunden! $Aktuelle_XML_Datei wird verschoben"
Move-Item "$Datei_als_xml" "$Aussortierte_Single"}}
if ($debuggingmodus-eq '1'){
#Feste Pfade von Source und Destiantion
$FIX_SOURCE
$FIX_DESTINATION
if ($FIX_SOURCE-eq 'C:\Users\Blabla'){
#Pfad des Backups/der Backupfiles
$BCKpfad
#Array wird erzeugt mit allen Dateinamen eines Dateityps
$Array_von_YYY_Dateien = Get-ChildItem "$Temppfad\*.*" -Filter "*.YYY"
#Der aktuelle Dateiname aus dem Array heißt z.B. wörtlich "Aktuelle Datei"
foreach ($Aktuelle_YYY_Datei in $Array_von_YYY_Dateien)
}else{for (2000, 1, i, ++)}Wenn ich jetzt noch eine IF-Anweisung in die Anweisung packe weiß man am Ende nicht mehr zu welchem Kommando die geschweifte Klammer gehört.
Das war ein einfaches Beispiel, denke aber auch das klar ist wie es laufen würde wenn man längeren oder komplexeren Text habe.
Danke euch fürs lesen.