bestpractice-naming

Best practice – Naming Guidelines

Die Lesbarkeit und Nachvollziehbarkeit unseres Codes hängt maßgeblich mit den Bezeichnungen zusammen die wir zum Entwickeln nutzen. Das befolgen einiger best practice sowie einer einheitlichen Konvention kann also einen positiven Einfluss auf die Entwicklung der Codebase haben und sollte nach Möglichkeit eingehalten werden. Das wichtigste Kriterium beim Auswählen einer Bezeichnung ist, dass Sie einfach verständlich und gleichzeitig genau bezeichnend für deren Funktion ist. In der Realität ist dies häufig eine sehr schwierige Aufgabe. Um Bezeichnungen einfacher wählen zu können sollten Klassen und Methoden den SOLID Prinzipien folgen.

 

Bezeichnungen sollen eure Intentionen aufzeigen

Das Überlegen von passenden Bezeichnungen kann beim Programmieren echt zum Problem werden. Einige Entwickler versuchen Namen abzukürzen, vereinfachen oder im schlimmsten Fall fast zu verschlüsseln. Schauen wir uns folgendes Beispiel an:

int d;
// elapsed time in days
int ds;
int dsm;
int faid;

Der Bezeichner „d“ könnte so ziemlich alles bedeuten. Der Author hat in diesem Fall einen Kommentar genutzt um einen Hinweis zu geben. Kommentare sollten allerdings nur genutzt werden, wenn es keine andere Möglichkeit mehr gibt den Code noch selbst sprechender zu gestalten und evtl. Folgen zu beschreiben.

int elapsedTimeInDays;
int daysSinceCreation;
int daysSinceModification;
int fileAgeInDays;

 

Vermeidet irreführende Informationen

Gar keine Information ist immer noch besser als eine irreführende. Manche Entwickler verstecken unabsichtlich teilweise wichtige Informationen.

Customer[] customerList;
Table theTable;

Die Variable „customerList“ ist eigentlich gar keine Liste. Es ist ein Array. Die Variable „theTable“ ist offensichtlich ein Objekt vom Typ Table mit dem unnützen Zusatz „the“. Hilfreicher wäre hier eine Information über den Inhalt.

Customer[] customers;
Table customers;

 

Achtet auf die Länge eurer Bezeichnungen

Moderne Sprachen haben keinerlei Probleme mit langen Bezeichnungen von Variablen oder Methoden. Dennoch können extrem lange Bezeichnungen zu chaotischen Verhältnissen im Code führen.

var theCustomersListWithAllCustomersIncludedWithoutFilter;
var list;

Eine gute Bezeichnung enthält genau so viele Worte um deren Konzept auf den Punkt zu bringen. Nicht mehr und nicht weniger. Zusätzliche Worte machen die Bezeichnung unnötig lang und schwerer zu verstehen. Auch zu kurze Bezeichnungen können schlecht sein wenn deren Konzept dadurch verloren geht.

var allCustomers;
var customersInOrder;

 

Folgt der Standardnotation um Code verständlicher zu gestalten

Es ist eine gute Idee der Microsoft .NET Notation beim gestalten von Code zu folgen. Die Resharper Einstellungen helfen uns dabei, dass der Stil wirklich eingehalten wird. Auch bei gewachsenen Strukturen mit unterschiedlichen Stilen ist es hilfreich zumindest neueren Code immer nach der Notation zu schreiben.

const int maxcount = 1
bool change = true
public interface Repository
private string NAME
public class personaddress
void getallorders()
const int MAXCOUNT = 1
bool isChanged = true
public interface IRepository
private string _name
public class PersonAddress
void GetAllOrders()

 

Verwendet ein einziges Wort für euer Konzept. Mischt keine Konzepte

Um besser zu verstehen, was hier mit Konzept gemeint ist betrachten wir folgenden Code:

//1.
void LoadSingleData()
void FetchDataFiltered()
Void GetAllData()
//2.
void SetDataToView();
void SetObjectValue(int value)
  1. Der Author verwendet hier 3 verschiedene Wörter um zu signalisieren, dass Daten geholt werden ( => Load, Fetch, Get ). Momentan fehlt uns hier die passende Richtlinie jedoch ist es eine gute Idee zumindest auf persönlicher Ebene einheitliche Bezeichnungen zu verwenden.
  2. Im zweiten Fall verwendet der Entwickler das Wort „Set“ für 2 unterschiedliche Anwendungskonzepte. „Lade Daten in die View“ und das „Setzen eines Wertes in ein Objekt“. Beide Konzepte unterscheiden sich sehr deutlich voneinander, verwenden aber dasselbe Wort. Solche Dinge gilt es eigentlich zu vermeiden.
//1.
void GetSingleData()
void GetDataFiltered()
Void GetAllData()
//2.
void LoadDataToView();
void SetObjectValue(int value)

 

Hilfe bei der Namenswahl? Hier sind einige schlechte buzzwords die man grundsätzlich nicht nutzen sollte

 

Simple

Was im Code ist jemals simpel? Und was soll das Wort in diesem Zusammenhang wirklich bedeuten?

Manager

Kaum ein buzzwort wird so häufig verwendet wie der Manager. Was tut der Manager eigentlich? Und inwieweit unterscheidet er sich von anderen Managern? Wenn ihr den Drang habt einen Manager zu erzeugen seid ihr eventuell drauf und dran eine neue Gottklasse zu erzeugen.

Helper

Auch sehr beliebt ist der Helper. Häufig vollgeklatscht mit statischen Extensionmethoden. Warum also nicht gleich sagen was die Klasse enthält? Extensionmethoden für einen bestimmten Typen? MyClassExtensions gibt mehr Aufschluss darüber was die Klasse enthält als MyClassHelper

Attribut / Attribute

Das Wort Attribut bzw. Attribute (engl.) sollte lediglich als suffix einer Klasse genutzt werden, wenn dies auch wirklich ein .NET Attribut ist. In allen anderen Fällen sollte dieses Wort vermieden werden.

Ex

Ex wurde häufig genutzt um zu signalisieren, dass es sich um eine Weiterentwicklung einer anderen Komponente handelt. Spätestens wenn es eine Weiterentwicklung der Weiterentwicklung geben soll wird klar, dass Ex nun doch nicht das gelbe vom Ei ist und somit eine ExEx oder Ex2 Bezeichnung herhalten müsste. Kann man die Information also nicht einfacher Verpacken? Man möchte durch dieses Suffix häufig eine Art Versionierung von Methoden oder Klassen erzeugen. Alte Funktionalitäten sollen unberührt bleiben aber der Name bleibt ja reserviert.

  • Einige öffentliche frameworks fahren den Ansatz ihre Methoden dabei einfach durchzunummerieren. Zusätzlich zur Methode AddNewCustomer() würde dann AddNewCustomer2() kommen und die alte Methode müsste Obsolete gekennzeichnet werden.
  • Man kann auch nach Möglichkeit die alte Methode in AddNewCustomerOld() umbenennen und die zu verwendende Methode als AddNewCustomer() anlegen. Obsolete kennzeichnen sollte man die alte Methode dennoch.