1. Abstract
The following document is intended to suggest and give concrete examples of the nomenclature to be used during the development of the back end and front end of a Board solution. The aim is to have a consistent and organized nomenclature that led to a maintainable solution that can be easily consulted in the event of additional developments, post-go-live support, and maintenance activities.
2. Context
During the development of a board application, the developer needs to create hundreds of back-end structures: entities, cubes, data readers, and procedures. The same for the front-end layer with the capsule and all the screens. In all the projects, these activities are a team effort, with several developers collaborating to create the necessary structures. On top of that, many applications require post-go-live support activities and or additional developments at a later stage of the project. For all these reasons becomes crucial to define a naming convention at the beginning of the development phase and apply it when any new structure is created, or an existing modified.
3. Content
During the development of a Board application, it is strongly suggested to define a nomenclature to be used for all the structures required to create the application.
For each of the back and front-end sections, guidelines are proposed below to help the developer to give a suitable nomenclature considering dos and don’ts.
A disciplined method, classification, and naming are essential for any activities of design and review of the solution.
3.1 Back End
3.1.1 Data Model
Consider the following guidelines to give a proper data model name:
- Do not use the client’s name in the Data Model name;
- Do name the Datamodel according to the application context, for example, "Business Intelligence", or “Planning”;
- Avoid using acronyms unless specifically requested by the customer and aligned to customer conventions;
- Do not use special characters in the Database name (for instance, avoid using the ampersand symbol, &).
3.1.2 Entities
Consider the following guidelines to properly name entities
- Do use the singular form – e.g., Version not versions;
- Do Capitalize only for appropriate acronyms (e.g., SKU);
- Do make every effort to align naming conventions with those used in source systems. E.g., If you are loading ‘GL Account’ from the source into an entity, it should be called GL Account, not Account.
- Avoid the use of special characters or punctuation;
- Do not rename or delete the [R] for replicated entities;
- If an entity becomes unused, prefix it with ZZ and create a dedicated group to store all the unused entities.
3.1.3 Cubes
During the development of a Board Solution, the developer will probably create hundreds of cubes with different meanings and for different purposes. That’s why the definition of a proper classification is key.
3.1.3.1 Classification Guidelines
An example of cube classification can be as follow.
Description + one/two digit + three digits:
- Description to describe the cube
- One digits to define how the cube is populated, for example
- [L] if loaded through DR
- [D] if populated through Data entry
- [C] if calculated through Data flow
- Three digits to describe how the cube is used
- [MTX] for matrix cubes
- [SET] for setting cubes
- [TCH] for technical cube
- [TMP] for temp cubes that can be cleaned at the end of the procedure
- [STG] for staging cubes
- [REP] for reporting cubes
Using the described naming convention, these are some cube name examples:
- ACT Sales [L][STG]: cube to store actual sales loaded though DataReader
- Current Year [D][SET]: setting cube to identify the current year
- Workflow Locker [C][TCH]: Technical cube to lock data entry based on Workflow status
- User-Role [L][MTX]: Matrix to assign user–role load through data Reader
Additional consideration:
- Add in the cube name the area/module where the cube is used. An alternative could be to use cube grouping, which is a powerful way to group, sort, and classify all the cubes created.
- Can be helpful to add in the cube name the physical name [Vxxx]. This will make the search easier during the configuration of a layout.
3.1.3.2 Nomenclature
- Do not use implied terms such as ‘Cube’.
- Do not use abbreviations unless specifically relevant.
- Do use Proper Capitalization. Do not use ALLCAPS.
- Do name cubes according to the classification guidelines described above.
- If a cube becomes unused, prefix it with ZZ, and empty it. Create a dedicated group to store all the unused cubes
3.1.4 Data reader
- Prefix data readers according to the following categories:
- E – Data reader to load an Entity
- H – Data reader to load and create hierarchies
- C – Data reader to load a cube
- Include the module name if relevant.
- Match the data reader name to the source file description when possible.
3.1.5 Procedures
3.1.5.1 Classification Guidelines
An example of classification for database and capsule procedure can be as follow.
- A prefix to define the relevant module name:
- BDG – Budget
- WRF - Workflow
- ADM – Admin Settings
- SYS - for system procedures such as backups
- A few digits to describe the procedure purpose, for example:
- LOAD - to identify procedures that load data
- OUT - to identify procedures that export data
- SAVE - to identify procedures that save data entered by the user
- GOTO – to identify procedures to navigate across the screen
- Description.
Using the described naming convention, these are some examples:
- BDG – LOAD – Expenses Target
- BDG – OUT – Export Expenses Baseline
- ADM – SAVE – Yearly Settings
- WRF – CALC – CC open
Additional considerations:
- Can be helpful to prefix unused or test procedures with ‘ZZ’. They will then show at the end of the procedure list and should be deleted before promoting to production.
- If unique to a screen, capsule procedure names should start with the screen number where they are used. Subsequent procedures used in the same screen should be enumerated 1.1, 1.2, etc. This can help identify the steps sequence the end user is following.
- Can be helpful to prefix with “CALL” a procedure that is called from multiple procedures. This is alerting the consultant that changing this procedure there can have an impact on any procedure that is calling it.
3.2 Front End
3.2.1 Capsule
3.2.1.1 Nomenclature
- Capsule names and their parent folder names are the first things a user will see when they land on the Board web home screen. Do ensure folder and capsule naming is relevant to the user audience, using business functional terms.
- Do not use ALLCAPS unless relevant to client branding.
- Do use proper capitalization.
- Do not use implied terms (e.g., ‘Capsule’).
- Do not use special characters.
3.2.1.2 Organization
- Capsules should be organized with navigation and folder security in mind.
- In a Sandbox environment, the structure of Capsules and folders should be exactly aligned to production. This is to assure testing is conducted in a like-for-like fashion and all capsule links are preserved (i.e., folder paths and capsule names remain consistent between environments.
- Create a dedicated folder for unused or deprecated capsules which is excluded from general user security profiles.
- Create a dedicated folder for Backups. Ideally, this should contain timestamped sub-folders. (This should also be excluded from general user security profiles).
3.2.2 Screen
3.2.2.1 Nomenclature
- The screen name appears in the top bar and will be identified by the end user as the screen title. Use a proper name that is consistent with the objective and purpose of the screen and meaningful for the end user.
- Do not use implied terms like ‘Screen’.
- Use proper capitalization.
- Do not use ALL CAPS.
- Do not use special characters.
3.2.2.2 Organization
- If the number of screens in the application is relatively small, it can be evaluated to start the screen name with a logical number sequence that reflects the logical navigation and workflow.
- Define sub-categories with a dot, but ideally, limit them to 3 levels. E.g., ‘1.1.1 Main Menu’, ‘3.1.1 Validate and Submit’. You should consider the most appropriate time to introduce the number pre-fix to avoid very frequent alterations to screen codes during the development.
- When testing or creating a temporary screen, prefix the screen name ‘ZZ’. ZZ screens should be deleted from the release candidate capsule and not promoted to production. An alternative could be to create an ad hoc test capsule.
3.2.3 Mask
3.2.3.1 Nomenclature
- Mask names are not displayed in any part of an application at run-time so naming conventions need to help the developer or power user.
- Unlike all other naming conventions, it is recommended to prefix masks with the implied term “Mask” because when multiple masks and screens are open in the Board thick client, it is not possible to differentiate them.
- Do not use ALLCAPS.
- Link the Mask name to the relevant module or audience.
- Keep it generic, in line with the mask content – like:
- MASK – Admin Settings
- MASK – Budget entry
- MASK – Reporting
