Archive for the ‘EGL Naming Conventions’ Category
This post presents a number of important and useful programming conventions. If you follow them your EGL code will be self-documenting and easier to read and maintain.
Naming and Capitalization Conventions
The standards that follow are derived from David Flanagan’s book, “Java In A Nutshell”, third edition. Since EGL development is similar to Java development these standards can apply to EGL as well. EGL development can often include Java code to help with tasks that EGL cannot perform and so adopting these standards will naturally apply to any Java source members included into the EGL project. Later, when the EGL developer endeavours to embark upon developing web applications using Java alone, they can apply the same standards they have been using all along for EGL and will serve to make that transition much easier.
The naming conventions refer to packages, EGL parts (programs, services, records, libraries, external types, etc.), functions, fields and constants in EGL. Because these conventions are universally followed in the Java development community and to some degree by the .NET community they are very well suited for the EGL development community. The naming standards for fields and functions can also be applied to RPG-Free.
EGL source files, whether they are for RichUI Handers, Services, External Types or Records, are organized into related groups known as packages and should be made unique by prefixing them with the inverted name of an internet name, such as “com.mig.application”.
Whether for Java or EGL, packages should follow the convention as shown.
com.mig.[project name].[package name].
Naming in this way will ensure they are unique enough to avoid name collision if packages encapsulated within a .jar file are included in the project. All package names should be lowercase.
- EGL Parts
All EGL parts are files used to create EGL applications. These are Logic parts including Program parts and Library parts, which are general-use parts, as well as Service parts, External-Type parts, and Handler parts, which have more specialized uses.
EGL part names should be nouns as they represent “things” or “objects”. (e.g. Customer, Invoice, Policy, etc.) The names for these parts should begin with a capital letter and be written in mixed case. If a part name consists of more than one word, each word should begin with a capital letter (e.g. CancerPolicyService, CustomerEntryHandler, ClaimsService etc.). If an EGL part, or one of the words in the part name is an acronym, the acronym can be written using capital letters (e.g. URL, HTMLParser).
Interface names follow the same capitalization conventions as EGL Parts. When an interface is used to provide additional information about the par that implements it, it is common to choose an interface name that is an adjective (e.g. Runnable, Cloneable, Serializable, DataInput). When an interface works more like an abstract representation of the part, use nouns (e.g. Document, FileName, Collection).
Function names should contain a verb as they are used to make an EGL Handler, Service or Program perform an action. Adjectives and nouns can be included in its name.
function showPage(newPage int in)
function toPage(newPage int in)
A function name always begins with a lowercase letter. If the name contains more than one word, every word after the first begins with a capital letter (e.g. insert(), addPolicy(), updateClaim(), etc.). Function names are typically chosen so that the first word is a verb. Function names can be as long as needed to make their purpose clear, but choose succinct names where possible.
- Variables and Constants
Nonconstant variable names should be nouns and should follow the same capitalization conventions as function names. If a field is a constant it should be written in uppercase. If the name of the constant includes more than one word, the words should be separated with underscores (e.g. MAX_VALUE, EMAIL_ADDRESS, MACHINE_ID, USER_PASSWORD, etc.) A field name should be chosen to best describe the purpose of the field or the value it holds.
The names of function parameters appear in the documentation for a function as presented by the IDE’s code assist facility. Therefore, you should choose names that make the purpose of the parameters as clear as possible. Try to keep parameter names to a single word and use them consistently. For example, if a CancerClaimService service-part defines many functions that accept a claim number as the first parameter, name this parameter claimNumber in each function.
- Local Variables
Local variable names are an implementation detail and never visible outside of the EGL Part. Nevertheless, choosing good names makes your code easier to read, understand, and maintain. Variables are typically named following the same conventions as functions and fields.