Hi all,
Today I’m focusing my attention on ADF naming conventions.
Beside this post I will write two more to cover as much as possible all areas of this subject. In the last post I will provide a PDF with all information covered in these series of posts.
Motivation
During ADF applications development we may encounter many development challenges. One of these challenges is about implementing a naming convention to be used by all project developers involved during implementation.
Each developer have his own background and his own ideas on how things should be implemented. We want them to have freedom of thought in order to get the best approaches to reach the goal, but what we really don’t want is to have multiple ways of doing the same thing, otherwise we might face really difficult challenges in the future, namely around software maintenance and bug tracing.
Also, the developer roster may change during project development. For the new ones who join we need to provide proper training. If we can follow conventions we will have shorter training periods and they will be brought to speed quicker while familiarizing with the application.
After the application is deployed in the production environment, we face a new challenge, Maintenance and Support. Big headaches usually start right there, and they can be even bigger if we don’t follow these important naming conventions in our applications’ code.
I have found some information here about this topic but we needed more, and we needed to instantiate it to our projects, so we decided to defined our own ADF Naming Conventions, to be used organization-wide on our ADF projects.
In this post I will share my experience and our ADF Naming convention rules regarding the following topics:
- Application & Project Naming
- Packages Naming
- Business Components Naming
Abbreviations
Consider the following terms used in these series of posts:
| Abbreviation | Definition | Example |
|---|---|---|
| PROJECT_NAME | Customer or project’s short name. Try to use only the necessary characters that are able to describe your customer/project so that everyone can understand it. | RMK (Red Mavericks) |
| MODULE_NAME | Provide a name that describes the target of the project (module). | MyAdfLib |
| DOMAIN_NAME | Internet domain name. | red.mavericks |
| BUSINESS_AREA | Feature Business area (retail, financial, etc.) | retail/financial |
Application & Project Naming
For Applications and Projects we defined the following naming rules:
| Application | Project |
|---|---|
| <PROJECT_NAME> + <MODULE_NAME> + AppExample: RMKMyAdfLibApp | <PROJECT_NAME> + <MODULE_NAME>
Example: RMKMyAdfLib |
IMPORTANT NOTE: For both previous naming rules, decide if they should be in upper case, lower case or camel case. Once you do, stick to it!
Packages Naming
In the wizard for creating a new application, you are prompted to set up the “Application Package Prefix“. This package prefix will define the root package for the projects contained in this new application.
The default “Application Package Prefix” for new applications should be:
<DOMAIN_NAME> + . + <PROJECT_NAME>
Example: red.mavericks.rmk
For each new project, you will inherit the application’s root package structure. Nevertheless you should configure it to have a distinct name from other projects. With this, you are able to identify your modules/libraries. The package structure for your project should follow the next pattern:
<DOMAIN_NAME> + . + <PROJECT_NAME> + . + <MODULE_NAME>
Example: red.mavericks.rmk.my.adf.lib
Business Components Naming
For this topic, we will provide our proposed package structure and file naming rules for Business Components.
IMPORTANT NOTE: Files should be named in camel case.
Packages Structure
For Business Components projects, we should gather Entity Objects, View Objects, View Links and Associations under the following packages::
| Type | Package | Description |
|---|---|---|
| Entity Associations | <DOMAIN_NAME>+ . +<PROJECT_NAME>+ . +<MODULE_NAME>+ adfc.entity.associations | Contain entity associations |
| Entity Objects | <DOMAIN_NAME>+ . +<PROJECT_NAME>+ . +<MODULE_NAME>+ adfc.entity.objects | Contain entity objects |
| View Links | <DOMAIN_NAME>+ . +<PROJECT_NAME>+ . +<MODULE_NAME>+ adfc.view.links | Contain view links |
| View Objects | <DOMAIN_NAME>+ . +<PROJECT_NAME>+ . +<MODULE_NAME>+ adfc.view.objects | Contain view objects |
| Model JPX File | <DOMAIN_NAME>+ . +<PROJECT_NAME>+ . +<MODULE_NAME>+ adfc | Contain model JPX file |
Example:
| Entity Associations: | red.mavericks.rmk.my.adf.lib.adfc.entity.associations |
| Entity Objects: | red.mavericks.rmk.my.adf.lib.adfc.entity.objects |
| View Links: | red.mavericks.rmk.my.adf.lib.adfc.view.links |
| View Objects: | red.mavericks.rmk.my.adf.lib.adfc.view.objects |
| Model’s JPX File: | red.mavericks.rmk.my.adf.lib.adfc |
File Naming
For each Business Component type, you should provide the following prefixes:
| File Type | Suffix | Example |
|---|---|---|
| Entity Associations | Assoc | SomeNameAssoc |
| Entity Objects | EO | SomeNameEO |
| View Links | VL | SomeNameVL |
| View Objects | VO | SomeNameVO |
| List Of Values | LOV | SomeNameLOV |
| Model JPX File | Equal to project’s name |
View Link File Naming
View Link names should be self-explanatory so we can easily identify their purpose. Based on this we defined the following pattern::
<ViewObjectSourceName> + <ViewObjectDestinationName> + VL
Example: EmployeeEmployeeBranchVL
Application Modules
You may have multiple “Application Modules” in your application. For this case we should be able to identify their purpose as well as their business area target. Based on this we followed the next pattern:
<PROJECT_NAME> + <MODULE_NAME> + AM
Example: RMKMyAdfLibAM
End of Part I – Next episodes…
In my next post I will talk about:
- Model & View Controller Projects
Cheers,
Pedro Gabriel
