Ansicht
Dokumentation

ABENTELLING_NAMES_GUIDL - TELLING NAMES GUIDL

TXBHW - Original Tax Base Amount in Local Currency   General Data in Customer Master  
Diese Dokumentation steht unter dem Copyright der SAP AG.

Sprechende Namen

Ein Bezeichner kann sowohl technische als auch semantische Informationen enthalten:

• Technische Informationen können sehr vielfältig sein. Beispiele für die Möglichkeiten bei einem Datenobjekt sind der Datentyp, der Kontext der Deklaration, ob ein Schnittstellenparameter per Wert oder per Referenz übergeben wird, etc.

• Die semantischen Informationen geben Aufschluss über den Zweck von Klassen oder Datentypen, den Inhalt von Datenobjekten, die Funktionalität von Methoden etc.

Die technischen Informationen zu einem Repository-Objekt oder einer programminternen Entität sind in der ABAP Workbench oft direkt zu sehen, werden über eine Quickinfo angezeigt oder sind lediglich einen Doppelklick weit entfernt. Die Semantik einer Variablen lässt sich dagegen ohne entsprechende Informationen im Bezeichner für den Leser oft ungleich schwerer herausfinden als rein technische Typinformationen.

Sprechende Namen vergeben

Wählen Sie alle Bezeichner so, dass sie die für ihren Kontext notwendigen semantischen Informationen enthalten und dabei leicht verständlich sind.

Ziel bei der Namensgebung ist es, möglichst sprechende und selbstdokumentierende Namen zu vergeben. Hierbei sollte stets problemorientiert und nicht implementierungsorientiert vorgegangen werden. Ein Wahrheitswert sollte beispielsweise nicht die Bezeichnung flag tragen, sondern einen Namen, der seine Bedeutung angibt, wie beispielsweise is_checked.

Bei der Wahl eines sprechenden, problemorientierten Namens sind im Einzelnen die folgenden Aspekte zu beachten:

• geeignete Wahl von Substantiven, Verben und Adjektiven

• vernünftiger Einsatz von Abkürzungen

• geeignete Trennung von Namensbestandteilen

Diese Punkte werden im Folgenden ausführlich diskutiert. Da man die rein technischen Informationen zu einem bezeichneten Objekt in aller Regel durch die Doppelklick-Navigation in der ABAP Workbench mühelos und sehr schnell einsehen kann, können diese als Namensbestandteile zugunsten semantischer Informationen entfallen.

Organisationen, ob SAP-intern oder -extern, die technische Informationen zusätzlich zu den semantischen Informationen in Bezeichnern vorschreiben wollen, können dies in eigenen Namenskonventionen festlegen, die auf unseren semantischen Regeln basieren. Wir sind allerdings der Überzeugung, dass die Codierung technischer Eigenschaften in Bezeichernamen nicht dazu geeignet ist, die Nachvollziehbarkeit oder Wartbarkeit von ABAP-Programmen, die gemäß der vorliegenden Richtlinien entwickelt wurden, zu erhöhen. Im Kontext anderer Programmiersprachen mit geringerer Typvielfalt und weniger leistungsfähigen Entwicklungsumgebungen mag sich dies anders verhalten.

Die Wahl von Substantiven, Verben und Adjektiven bei der Namensgebung ist abhängig von der zu bezeichnenden Entität:

• Pakete und Paketschnittstellen

Ein Paket umfasst eine Sammlung von Repository-Objekten zu einem bestimmten Sachgebiet. Der Name eines Paketes kann entweder aus einem oder mehreren Substantiven im Singular bestehen, die das Sachgebiet bezeichnen, wie beispielsweise sabp_compiler, oder aus einem oder mehreren Substantiven im Plural, welche die enthaltenen Objekte bezeichnen, wie zum Beispiel in sabp_analyze_tools. Unterpakete beginnen mit dem Namen des Oberpaketes und enthalten Suffixe, welche die Spezialisierung ausdrücken. Der Name einer Paketschnittstelle beginnt mit dem Namen des Paketes. Informationen zur Sichtbarkeit oder die Einschränkung auf bestimmte Verwender werden optional als Suffix angehängt, wie beispielsweise _public, was für Öffentliche Schnittstelle steht, oder _verification für Schnittstelle zu Verifikationswerkzeugen.

• Datentypen, Klassen und Interfaces

Diese bezeichnen Kategorien von Dingen und werden daher mit Substantiven bezeichnet, wie beispielsweise in cl_abap_conv_codepage. Mit zunehmendem Grad der Spezialisierung steigt die Anzahl der Substantive, die zur Beschreibung notwendig sind. Dies kann dann zu längeren zusammengesetzten Namen führen wie bei if_abap_string_writer oder cl_abap_xml_name_converter. Bei Bedarf kann der Name auch durch ein zusätzliches Adjektiv präzisiert werden, so geschehen in if_serializable_object und cl_abap_ weak_reference. Die Bezeichnung einer Kategorie erfolgt in der Regel im Singular, weshalb ein Klassenname im Allgemeinen auch aus Substantiven im Singular bestehen sollte. Für Abweichungen von dieser Regel gibt es allerdings auch viele Beispiele, wie etwa cl_ abap_memory_utilities. Solche Klassen modellieren dann häufig keine Kategorie, sondern stellen ein Sammelsurium an thematisch lose gekoppelter Funktionalität zur Verfügung, meist in Form ausschließlich statischer Methoden.

• Assoziationen

Diese bezeichnen eine semantische Beziehung zwischen einem Startobjekt und einem Zielobjekt. Um diese Beziehung bei der Verwendung einer Assoziation in einer Pfadangabe deutlich zu machen sollten Assoziation mit dem Zeichen _ gefolgt von einer Bezeichnung, die bei nichtreflexiven Assoziationen den Namen des Zielobjekts enthält, bezeichnet werden.

• Variable Datenobjekte und Schnittstellenparameter

Diese bezeichnen Eigenschaften und werden daher mit einem Substantiv bezeichnet, wie beispielsweise cl_abap_regex->pattern. Wahrheitswerte werden, analog zum natürlichen Sprachgebrauch, durch das Voranstellen von is_ gekennzeichnet. Handelt es sich bei der zu bezeichnenden Eigenschaft um eine Menge (in ABAP meist um eine interne Tabelle), sollte dies durch den Plural ausgedrückt werden; so geschehen zum Beispiel beim Schnittstellenparameter matches der Methode cl_abap_matcher->find_all.

• Konstanten

Technisch gesehen, handelt es sich hierbei um Datenobjekte, deren Werte zur Programmlaufzeit unveränderlich sind. Diese bezeichnen spezielle, unveränderliche Eigenschaften. Ihre durch Substantive zu bezeichnenden Werte heben sich daher durch eine bestimmte Eigenschaft hervor (beispielsweise Minimalgröße, Startwert etc), die durch ein oder mehrere zusätzliche Adjektive ausgedrückt werden. Beispiele hierfür sind cl_abap_exceptional_values=>decfloat34_max und cl_abap_format=>o_sign_as_postfix.

• Ereignisse

Diese werden durch einen Ausdruck im Present Perfect beschrieben, der das Eintreten beschreibt, so geschehen bei cl_dd_form_element->button_ clicked und cl_gui_alv_tree->selection_changed (In diesem Beispiel ist das Substantiv sehr stark abgekürzt (o für output format). Zu sinnvollen Abkürzungen siehe weiter unten.)

• Vorgehensweisen

Neue Prozeduren sind nach Regel ABAP Objects verwenden Methoden. Hier müssen verschiedene Fälle unterschieden werden:

• Ereignisbehandler werden nach dem zugehörigen Ereignis benannt und zusätzlich mit einem Präfix versehen, das sie als Behandlermethoden ausweist. In ABAP hat sich das Präfix on_ durchgesetzt, das dem natürlichen Sprachgebrauch folgt und eine Methode gut sichtbar als Ereignisbehandler kennzeichnet. Für die beiden genannten Ereignisbeispiele wären die zugehörigen Behandlermethoden demnach on_button_ clicked bzw. on_selection_changed zu benennen.

• Der Name von Methoden mit Rückgabewert (funktionale Methoden) beschreibt das zurückgelieferte Ergebnis. Vorangestellt wird ein get_, um die Aufgabe der Methode zu beschreiben. Ein Beispiel hierfür ist die Methode cl_abap_exceptional_values=>get_max_value. Liefert die Methode einen Wahrheitswert, wird statt des get_ ein is_ vorangestellt. get_-Methoden sollen in ABAP im Allgemeinen den Rückgabewert beispielsweise durch Berechnung bestimmen. Für die bloße Rückgabe von Attributwerten sollen, anders als beispielsweise in Java, keine eigenen Methoden verwendet werden. ABAP bietet für solche Zwecke schreibgeschützte (READ-ONLY) Attribute an.

• In allen übrigen Fällen beschreibt der Name einer Methode eine auszuführende Tätigkeit. Folglich ist hier der Methodenname ein Verb, im Allgemeinen im Imperativ. Beispiele: cl_abap_regex->create_ matcher and cl_abap_memory_utilities=>do_garbage_collection. Methoden, die zum Setzen von Attributen dienen, werden mit dem zu setzenden Attribut bezeichnet, dem ein set_ vorangestellt wird. Andere Prozeduren (Funktionsbausteine und Unterprogramme), die noch zum Verschalen von Methodenaufrufen notwendig sind, werden entsprechend bezeichnet.

• Ausnahme

Diese beschreiben unerwartete Zustände. Technisch handelt es sich hierbei um Klassen. Klassische Ausnahmen sollen nicht mehr verwendet werden. Abgesehen von dem Präfix, gelten für sie jedoch die gleichen Überlegungen. Zur Unterscheidung von regulären Klassen werden sie mit einem eigenen Präfix cx_ versehen, sofern es sich um globale Ausnahmeklassen handelt. Der Name einer Ausnahme soll den beanstandeten Zustand möglichst sprechend wiedergeben, wie beispielsweise cx_sy_offset_not_allowed. Liegt eine ganze Hierarchie von Ausnahmeklassen vor, beschreiben die Namen der Oberklassen keine speziellen Ausnahmesituationen, sondern Fehlerkategorien (wie cx_sy_data_access_error im genannten Beispiel).

Abkürzungen als Namensbestandteile sollen - soweit möglich - vermieden werden. Ausnahmen von dieser Regel sind Abkürzungen, die üblicherweise den Gebrauch des gesamten Begriffs ersetzen, wie zum Beispiel GUI oder XML. Wenn sich die Verwendung von anderen Abkürzungen aus Platzgründen jedoch nicht umgehen lässt, sollen zunächst allgemein gebräuchliche Abkürzungen benutzt werden.

Gibt es keine gebräuchliche Abkürzung, soll folgendermaßen vorgegangen werden: Vokale, die nicht am Wortanfang stehen, werden weggelassen. Diese sind für den Wiedererkennungswert von untergeordneter Bedeutung. Handelt es sich am Wortanfang um einen Doppelvokal, bleibt dieser jedoch im Ganzen erhalten, um die Wiedererkennung zu erleichtern (beispielsweise outbnd als Abkürzung für outbound, und nicht otbnd). Sollte eine weitere Verkürzung notwendig sein, können zusätzlich Doppelkonsonanten durch einfache ersetzt werden. Auch nach einem solchen Schritt bleibt das Wort im Allgemeinen erkennbar.

Ein Beispiel für eine unglücklich gewählte Abkürzung wäre beispielsweise ein tstmp für timestamp. Diese Abkürzung, die nicht den genannten Regeln folgt, ist wenig intuitiv. Ins Auge fallen zunächst die möglichen Bestandteile tst oder tmp, die an test bzw. temporary erinnern. Ein Zusammenhang mit timestamp ist hingegen auf Anhieb kaum auszumachen. Bei der Bildung von Abkürzungen ist daher auch darauf zu achten, dass das Ergebnis nicht einer anderen, möglicherweise gebräuchlicheren Abkürzung für einen ganz anderen Begriff zu ähnlich ist.

Bei der Bildung von Abkürzungen in einer anderen Sprache als der eigenen Muttersprache besteht die Gefahr, dass das Ergebnis unbeabsichtigt ein Wort oder eine Abkürzung ganz anderer Bedeutung darstellt. In Zweifelsfällen sollte dies durch Eingabe der Abkürzung in eine Suchmaschine überprüft werden. Wenn Sie beispielsweise nur vier Stellen zur Verfügung haben und button ausdrücken wollen, wählen Sie besser (gemäß den genannten Verkürzungsregeln) bttn und nicht einfach die ersten vier Buchstaben.

Grundsätzlich ist es sinnvoll, Namensbestandteile zur Erhöhung der Lesbarkeit optisch voneinander zu trennen. Hierzu bietet sich in ABAP der Unterstrich an. Eine Trennung von Namensbestandteilen durch Groß-/Kleinschreibung, wie sie beispielsweise in Sprachen mit C-artiger Syntax praktiziert wird, ist in ABAP nicht sinnvoll. Unterstriche in einem Namen weisen diesen normalerweiser als Bezeichner aus, da ABAP-Wörter im Allgemeinen nicht auf diese Weise gebildet werden. Ausnahmen bilden hier lediglich einige Formatoptionen zu Zeichenketten-Templates (wie beispielsweise SCIENTIFIC_WITH_LEADING_ZERO), die allerdings nur innerhalb von Zeichenkettenausdrücken vorkommen können, sowie einige wenige Zusätze zu SELECTION-SCREEN und WRITE.

Von der Verwendung von Ziffern als Namensbestandteilen ist abzuraten. Sie sind häufig ein Hinweis auf schlecht gewählte (weil wenig aussagekräftige) Namen oder deuten auf die Verwendung mehrerer Einzelvariablen hin, bei denen der Einsatz einer internen Tabelle sinnvoller wäre. Ausnahmen hiervon sind die Schnittstellenparameter von Prozeduren. Bei diesen kann eine Nummerierung gleichartiger Parameter durchaus sinnvoll sein.

Der Einsatz von Ziffern zur Bildung phonetischer Namen ist ebenfalls problematisch, da diese eine gewisse Gewöhnung voraussetzen und sich ihre Bedeutung nicht immer jedem leicht erschließt. Ein abschreckendes Beispiel ist trmn8r für terminator. Als vertretbare Ausnahme kann hier lediglich die recht gebräuchliche 2 für to gelten, die häufig als Namensbestandteil in Konvertierungsprozeduren anzutreffen ist und sich leicht interpretieren lässt, wie zum Beispiel in convert_itf_2_html.

Hinweise

• Es muss immer beachtet werden, dass die Informationen, die ein Bezeichner enthält, auch gültig bleiben müssen. Das gilt für semantische, insbesondere aber auch für technische Informationen. Wenn sich beispielsweise eine technische Information, die in einem Namen enthalten ist, durch eine Refactoring-Maßnahme ändert, müssen alle diesbezüglichen Namen und deren Verwender angepasst werden. Innerhalb freigegebener Schnittstellen ist das jedoch nicht leicht möglich. Bezeichner, die falsche Informationen liefern, sind im Zweifelsfall schlechter als Bezeichner, die gar keine Informationen liefern. Es soll Programmierrichtlinien geben, die aus diesem Grund sogar ausschließlich inhaltslose Bezeichner vorschlagen. Da sich semantische Eigenschaften mit viel geringerer Wahrscheinlichkeit im Laufe der (Weiter-)Entwicklung ändern, als dies für technische Eigenschaften der Fall ist, sind unsere im Wesentlichen semantischen Vorgaben zur Namensgebung aber auch in diesem Sinne hinreichend robust gegenüber Programmänderungen.

• Weniger ist oft mehr. Die genannten Vorschläge sollen Anhaltspunkte dafür sein, wie Bezeichner zusammengesetzt werden sollen, um die in einem Kontext notwendigen Informationen zu enthalten. Sie sollen aber auch nur in den Fällen eingesetzt werden, in denen die Bedeutung eines Bezeichners aus seinem Zusammenhang heraus nicht vollkommen offensichtlich ist. Zum Beispiel:

METHOD do_something.
  CONSTANTS lcv_maximum_do_loop_count TYPE i VALUE 100.
  DO lcv_maximum_do_loop_count TIMES.
    ...
  ENDDO.
ENDMETHOD.

Hier ist der lange Bezeichner lcv_maximum_do_loop_count der Lesbarkeit eher abträglich. Da eine Methode immer nur eine überschaubare Anzahl von Anweisungen enthalten darf, kann in einem einfachen Fall durchaus auch ein ganz einfacher Bezeichner gewählt werden:

METHOD do_something.
  CONSTANTS nmax TYPE i VALUE 100.
  DO nmax TIMES.
    ...
  ENDDO.
ENDMETHOD.

Ein weiteres Beispiel, wo kurze Namen sinnvoll sind, sind in LET-Ausdrücken deklarierte Hilfsfelder.

Folgender Quelltext zeigt die Deklaration einer Klasse, die arithmetische Berechnungen ausführt. Dies ist als synthetisches Beispiel zur Namensgebung zu verstehen. Es ist in ABAP natürlich in keiner Weise sinnvoll, die arithmetischen Operationen auf elementaren numerischen Datentypen über eine Klasse zu verschalen. Die Namen der Klasse und ihrer Methoden sind unnötig kurz, und die Namen der Schnittstellenparameter haben keinerlei semantische Bedeutung.

CLASS calcltr DEFINITION.
  PUBLIC SECTION.
    METHODS: add IMPORTING a        TYPE i
                           b        TYPE i
                 RETURNING VALUE(c) TYPE i,
             sub IMPORTING a        TYPE i
                           b        TYPE i
                 RETURNING VALUE(c) TYPE i,
             mul IMPORTING a        TYPE i
                           b        TYPE i
                 RETURNING VALUE(c) TYPE i,
             div IMPORTING a        TYPE i
                           b        TYPE i
                 RETURNING VALUE(c) TYPE f.
ENDCLASS.

Folgender Quelltext zeigt die gleiche Klasse wie obiger Quelltext, wobei die Namen der Klasse und ihrer Methoden jetzt ausgeschrieben sind und die Namen der Schnittstellenparameter ihre semantische Bedeutung ausdrücken.

CLASS calculator DEFINITION.
  PUBLIC SECTION.
    METHODS: add IMPORTING addend1           TYPE i
                           addend2           TYPE i
                 RETURNING VALUE(sum)        TYPE i,
        subtract IMPORTING minuend           TYPE i
                           subtrahend        TYPE i
                 RETURNING VALUE(difference) TYPE i,
        multiply IMPORTING factor1           TYPE i
                           factor2           TYPE i
                 RETURNING VALUE(product)    TYPE i,
          divide IMPORTING dividend          TYPE i
                           divisor           TYPE i
                 RETURNING VALUE(quotient)   TYPE f.
ENDCLASS.

Da die Operanden von Addition und Multiplikation kommutativ sind, können hier sinnvoll Ziffern zu ihrer Unterscheidung eingesetzt werden.

ABAP Short Reference   BAL Application Log Documentation  
Diese Dokumentation steht unter dem Copyright der SAP AG.

Length: 23718 Date: 20240523 Time: 103701     sap01-206 ( 358 ms )