GUIDELINE 4.6
Descriptive Names
ABAP_BACKGROUND
A name can include technical and semantic information:
Technical information can be very versatile. Examples of options in a
data object: data type, declaration context, whether a procedure
parameter is passed by value or by reference.
The semantic information indicates the purpose of classes or data types,
the content of data objects, the functionality of methods, and so on.
The technical information about a repository object or program-internal
entity can be viewed directly in the ABAP Workbench. This information is
also displayed in tooltips or can be displayed with a simple
double-click. However, in contrast to purely technical type information,
the semantics of a variable are more difficult to identify without the
relevant information in the name.
ABAP_RULE
Assign descriptive names
Always choose names that include the semantic information required for
your context and that also easy to understand.
ABAP_DETAILS
The aim is to assign descriptive and self-documenting names. You should
always follow a problem-oriented approach instead of an impl
ementation-oriented approach. For example, a truth value should not be
named flag . Instead it should have a name that indicates its
meaning, such as is_checked .
When you select a descriptive, problem-oriented name, you should
consider the following aspects in particular:
Appropriate use of nouns, verbs, and adjectives
Meaningful use of abbreviations
Appropriate separation of name components
These points are discussed in detail in the following sections. The
purely technical information for a named object can be displayed quickly
and easily, using double-click navigation in the ABAP Workbench.
Therefore, this information can be omitted from names and semantic
information can be used in names instead.
Any organizations (within SAP or external) that want to specify
technical information in addition to semantic information in names, can
define their own naming conventions that are based on our semantic
rules. However, we believe that coding technical attributes in names is
not suitable for making ABAP programs (developed according to the
present guidelines) easier to understand and maintain. This may be
different in the context of other programming languages with fewer types
and less powerful development environments.
The use of nouns, verbs, and adjectives for naming depends on the entity
that you want to name:
Packages and package interfaces
A package comprises a collection of repository objects for a specific
subject area. The package name can either consist of one or more
singular nouns that describe the subject area (such as
sabp_compiler
), or one or more plural nouns that indicate the contained objects
(such as sabp_analyze_tools ). Subpackages start with the name of
the super package and contain suffixes that indicate the specialization.
The name of a package interface starts with the name of the package.
Information on visibility or restrictions for certain users are attached
as a optional suffix. For example, _public , stands for public
interface and _verification stands for interface to verification
tools.
Data types, classes and interfaces
They denote categories of things and are therefore named using nouns,
for example, cl_abap_codepage . The greater the degree of
specialization, the greater the number of nouns required for
description. This can result in longer, combined names, for instance,
if_abap_string_writer or cl_abap_xml_name_converter . If
necessary, the name can be further specified with an additional
adjective, as in if_serializable_object and
cl_abap_weak_reference . The name of a category is usually written in
the singular form. Therefore, a class name should generally consist of
singular nouns. However, there are many examples of deviations from this
rule, such as cl_abap_ memory_utilities . These classes often do
not model a category but instead provide a hodgepodge of loosely related
functions, usually in the form of exclusively static methods.
Variable data objects and procedure parameters
These describe properties and are therefore named with a noun, for
instance, cl_abap_regex- pattern . Truth values are labeled using
the is_ prefix, which is consistent with natural language usage.
If the property you want to describe is a quantity (usually an internal
table in ABAP), this should be expressed using the plural. For example,
the matches parameter of the cl_abap_matcher- find_all
method.
Constants
From a technical point of view, these are data objects with unchangeable
values at program runtime. They describe special, unchangeable
properties. Values of constants are described with nouns. They are
distinguished by a specific property (such as minimum size, start value)
expressed by one or more additional adjectives. Examples:
cl_abap_exceptional_values= decfloat34_max and
cl_abap_format= o_extended_monetary .
Events
They are named using an expression in present perfect that describes
their occurrence, for example, cl_dd_form_element- button_clicked
and cl_gui_alv_ tree- selection_changed . In this example, the
noun is abbreviated significantly ( o for output format).
More information on useful abbreviations can be found below.
Procedures
New procedures are methods according to the
use ABAP objects rule. Here, we
distinguish between different cases:
Event handlers are named after the corresponding event. They are
assigned a prefix that identifies them as handler methods. In ABAP, the
on_ prefix has established itself. This is consistent with
natural language use and clearly labels a method as an event handler.
For the two event examples above, the names of the corresponding handler
methods would be on_ button_clicked and on_selection_changed
.
The name of methods with a return value (functional methods) describes
the returned result. The get_ prefix is added to describe the
task of the method. An example of this is the
cl_abap_exceptional_values= get_max_value method. If the method
returns a truth value, is_ is prefixed instead of get_ . In
ABAP, these get_ methods are generally supposed to determine the
return value (by using a calculation, for example). Unlike in Java, for
example, no own methods should be used to simply return attribute
values. Instead you should use the
write-protected ( READ-ONLY ) attributes provided in ABAP.
In all other cases, the name of a method describes an activity to be
performed. Therefore, the method name is a verb, generally expressed in
the imperative. Examples: cl_abap_regex- create_ matcher and
cl_abap_memory_utilities= do_garbage_collection . Methods used to set
attributes are described using the relevant attribute, which is prefixed
with set_ . Other procedures (
function modules and subroutines
) required to wrap method calls are named accordingly.
Exception
Exceptions describe unexpected states. Technically they are classes.
Classic exceptions should no longer be
used. Except for the prefix, the same considerations apply here. To
differentiate exceptions from normal classes, they are assigned their
own prefix cx_ , provided that
they are global exception classes. The name of an exception reflects the
rejected state as clearly as possible, for instance,
cx_sy_offset_not_allowed . If an entire hierarchy of exception classes
exists, the names of the superclasses do not describe special exception
situations. Instead they describe error categories (such as cx_
sy_data_access_error in this example).
You should avoid using abbreviations as name components wherever
possible. Exceptions to this rule are abbreviations that are usually
used instead of the complete term, such as GUI or XML . However,
if the use of certain abbreviations cannot be avoided due to restricted
space, you should initially use common abbreviations.
If no common abbreviation exists, you should proceed as follows: Vowels
are omitted, unless they are the first letter of the word. They are of
minor significance for the recognition value. If a word starts with a
double vowel, both letters are kept for ease of recognition (for
example, outbnd as the abbreviation for outbound instead
of otbnd ). If further abbreviations are required, you can replace
double consonants with single consonants. Even after this step, the word
is generally still recognizable.
An example of a poorly chosen abbreviation would be tstmp for
timestamp . This abbreviation does not follow the above rules and
is not intuitive. Readers would probably initially think of the possible
components tst or tmp , which would remind them of test
or temporary . However, an association to timestamp is
in initially very difficult to identify. Therefore, if you create
abbreviations, you must ensure that the result is not similar to
another, possibly more common abbreviation for a completely different
term.
When you create abbreviations in a foreign language, you run the risk
that the result represents a word or abbreviation with a completely
different meaning. If in doubt, you should enter the abbreviation in a
search engine to check it. For example, you only have four characters
available and you want to use the word button . In this case, you
should select the abbreviation bttn (following the abbreviation
rules above), instead of the first four characters.
Generally, it is useful to visually separate the name components, by
using the underscore in ABAP. This makes the names easier to read.
Separating name components with uppercase and lowercase (common in
languages with C-like syntax) is not
useful in ABAP. Underscores normally identify a name, because ABAP
words are usually not formed this way. The only exceptions here are cer
tain format options for character string templates (such as
SCIENTIFIC_ WITH_LEADING_ZERO ), which can only occur within character
string expressions, and certain additions to SELECTION-SCREEN and
WRITE .
You should not use digits as name components. They are often a sign of
poorly selected names (because they are not very descriptive) or
indicate the use of several individual variables, where the use of an
internal table would make more sense. Exceptions include the interface
parameters of procedures. Numbering similar parameters definitely makes
sense here.
The use of digits to form phonetic names is also problematic because
they require a degree of familiarization, and their meaning is not
always obvious to everyone. A particularly bad use of digits is the
abbreviation trmn8r for terminator . The commonly used
2 for to is the only justifiable exception here. This is often
found as a name component in conversion procedures and can be
interpreted easily ( convert_itf_2_html , for example).
Note
You must always keep in mind that the information included in a name
must remain valid. This applies to semantic information, but especially
to technical information. If, for example, technical information
included in a name changes due to a refactoring measure, all
relevant names and their users must be modified. However, this is not an
easy task in released interfaces. If in doubt, remember that names
containing incorrect information are worse than names that do not
provide any information at all. This is why programming guidelines exist
that suggest only using nondescript names. Since semantic properties are
less likely to change in the course of (further) development than
technical properties, our predominantly semantic specifications for
naming are relatively well safeguarded from program changes.
Note
Less is often more. Our suggestions indicate how to compose names to
include the information that is necessary in a context. They should only
be used when the meaning of the name is not completely obvious from the
context. For example:
METHOD do_something.
CONSTANTS lcv_maximum_do_loop_count TYPE i VALUE 100.
DO lcv_maximum_do_loop_count TIMES.
...
ENDDO.
ENDMETHOD.
The long name lcv_maximum_do_loop_count is quite difficult to
read. A method can only include a manageable
number of statements . Therefore, you can select a very simple name in
simple cases:
METHOD do_something.
CONSTANTS nmax TYPE i VALUE 100.
DO nmax TIMES.
...
ENDDO.
ENDMETHOD.
Bad Example
The following source code shows the declaration of a class that executes
arithmetic calculations. This should be understood as a synthetic naming
example. Of course, in ABAP, it makes absolutely no sense to
wrap the arithmetic operations on
elementary numeric data types using a class. The names of the class and
its methods are unnecessarily short, and the names of the method
parameters have no semantic meaning at all.
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.
Good Example
The following source code shows the same class as in the code above, but
the names of the class and its methods are now spelled in full, and the
names of the method parameters indicate their semantic meaning.
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.
Because the addition and multiplication operands are commutative, you
can use digits here to differentiate between them.
Documentation extract taken from SAP system, � Copyright SAP AG. All rights reserved