Naming conventions
Note: You may wish to view the how-to video on this subject.
Hackolade Studio includes the ability to maintain both a ‘business name’ and a ‘technical name’ for objects (containers, entities, and attributes.) To facilitate the maintenance of these 2 names, it is possible to keep them synchronized and transformed based on a set of user-driven parameters, and optionally based on a conversion file maintained outside of the application. Name conversion can go both directions: Business-to-Technical, or Technical-to-Business. Furthermore, when performing reverse-engineering, it is assumed that the database instance contains technical names, to be transformed in business names.
If you do not wish to use this feature, keep disabled the Name Coupling parameter (see below) and simply leave the technical name property blank, so the (business) name property is used by default.
Starting with version 4.1.2, we have replaced global parameters with separate target-specific parameters to allow different behavior depending on target. Also, the parameters are stored in a JSON file in the C:\Users\%usernames%\.hackolade\options\<targetname> directory, so they can be shared with teammates via Git.
Conversion file
A conversion file is not mandatory to use the Naming Conventions feature. A conversion file is a .csv file listing words that may appear in object names (business name), with a corresponding technical name to use instead in database definition scripts.
The conversion file is made of at least 2 columns, with Business Name as a first column, and Technical Name as the second column. Additional columns are ignored by Hackolade. The columns are separated by commas. The first line is the header line, and is ignored in the conversion. The lines are separated by a <CR><LF>. There is no limit to the number of lines in the file. The values in the columns are not case-sensitive. A case conversion may be applied in the conversion parameters, cfr below.
Example:
Business Name,Technical Name,Optional Description
account,acct,
customer,cust,
feedback,fdbak,
Important note: if your file contains diacritics (accents, ...) you must save your file with UTF-8 encoding for the function to work properly. If you edit the file using Excel, you should make sure to save it using this CSV UTF-8 option:
Conversion parameters
Conversion parameters are specific to each target. To modify the behavior of the name sync feature for a target, user options can be set in Tools > Options > Naming Conventions:
Application target: select the target for which these parameters apply
Default name coupling: 3 options are available from the dropdown box: No, Business-to-Technical, or Technical-to-Business.
Specify path and file name of the conversion file, or choose to Convert without a file and using the only the rules specified below. If you update the file while Hackolade is open, you may press the refresh button to reload the file.
Display: choose to see the Business name or the Technical name in the Object Browser, ER Diagram and hierarchical schema view
Business-to-Technical Conversion: the following options, if enabled will be applied after the file conversion (with or without file.)
Remove vowels: when this option is enabled, the vowels in the name are suppressed
Invalid characters: the characters declared can optionally be removed or replaced by another character. Example of invalid characters: "!?.,:;()=+-*@/\", and replacing character: "_"
Case conversion: choose from the dropdown:
- none: no case conversion is performed
- camelCase: also know as lowerCamelCase, words are joined together, and the first letter of the first word is lowercase, while the first letter of the subsequent words is capitalized
- PascalCase: also know as UpperCamelCase, words are joined together, and the first letter of every word, including the first one, is capitalized
- lowercase: all letters are converted to lowercase
- UPPERCASE: all letter are converted to UPPERCASE
- snake_case: all letters are converted to lowercase, plus words are separated with a underscore "_"
- kebab-case: all letters are converted to lowercase, plus words are separated with a dash "-"
- dot.case: all letters are converted to lowercase, plus words are separated with a dot "."
- path/case: all letters are converted to lowercase, plus words are separated with a slash "/"
Technical-to-Business Conversion: the following options, if enabled will be applied after the file conversion (with or without file.)
Case conversion: If enabled, a space is inserted between words detected in the technical name (based on the presence of a separator such as underscore (‘_’), a dash (‘-‘), a dot (‘.’), a slash (‘/’), or simply an Upper case letter). Choose from the dropdown:
- none: no case conversion is performed
- lower case: all letters are converted to lowercase
- UPPER CASE: all letter are converted to UPPERCASE
- Proper case: the first letter of every word is capitalized – no exceptions
- Title case: the first letter of every word is capitalized, except for certain small words, such as articles and short prepositions
- Sentence case: only the first letter of the sentence or phrase is capitalized
Upon exit of the dialog (via OK or Apply) after making a change in parameters, the user will be prompted to choose whether: to apply the changes to just previously coupled names, to apply the changes to all object names, or to not apply any of the changes performed by canceling the dialog.
Properties Pane
In the properties pane, the relationship between business name and technical name can have 3 states: OFF (default), convert Business name to Technical name, or convert technical name to business name. This state can be set separately for each individual object. To set Naming Conventions to control the business names and technical names of all objects, select Tools > Options > Naming Conventions, then choose either Business-to-Technical or Technical-to-Business from the dropdown "Enable name coupling".
Let’s say we have this starting situation:
To indicate that coupling is OFF between business and technical name, the 2 = sign icons to the right are un-selected. The user could simply type the technical name of his choice, without any compliance to the glossary file.
Now, if the user wants to apply naming convention by using the conversion file referenced in the parameters, he would just click on the = sign to the right of the Technical name:
where the = sign icon shown as pressed, and the Business name is converted into the Technical name by using the conversion file and other conversion parameters. While the = sign icon is ON, the Technical name field is locked and cannot be edited.
If the Technical name = sign icon is pressed again, the entry field is unlocked and the entry can be edited again:
If the Business name = sign icon is pressed this time, the Technical name is converted into the Business name by using the conversion file and other conversion parameters. While the = sign icon is ON, the Business name field is locked and cannot be edited.
Behavior during Reverse-Engineering
During Reverse-Engineering, if coupling parameters is set to 'No', then all object names from the source (whether from a DB instance, XSD, DDL, Excel, JSON, etc...) are stored in the Business Name property.
If coupling is set to either Business-to-Technical, or Technical-to-Business, the result of the Reverse-Engineering is the same. In both cases, the object names from the source are stored in the Technical Name property and converted to Business Name using the conversion parameter. That's intuitively obvious when the coupling parameter is set to Technical-to-Business.
But you may wonder why the handling is done as such when the coupling parameter is set to Business-to-Technical... The following dialog is presented to the user:
The only safe method we can ensure is one by which the Technical Name come from the source is preserved, no matter the conversion parameters. Say we have a source object called cust_acct and the Technical-to-Business is set in such a way that the Business Name becomes Cust Acct. If the application applies Business-to-Technical conversion that would be set for example to camelCase, the Technical Name would be changed to custAcct, thereby losing the original cust_acct in the source. We prefer to let the user choose the expected outcome to either keep it as is, or to change the parameters and apply these changes to the model.
Clearing all Technical Names
You may wish to disable any coupling between Business and Technical Names and maintain both manually. You may also decide that you want to empty all Technical Name properties. You may do so by setting coupling to No. When you get the following dialog:
you may choose to check the box "Clear all Technical Names". Be careful of course. You may want to save a version of your model prior to applying this clearing, and test that the behavior matches your expectations.
Advanced considerations
Conversion file
Entries in the conversion file can be in any order, and are case insensitive. You may declare individual words as well as expressions where words in an expression may have a different abbreviation than their individual abbreviation, or than in another expression. Example:
| Business Name | Technical Name |
|---|---|
| Customer | cust |
| Account | accnt |
| Customer Account | cstacc |
| Customer Account Center | cac |
Conversion rules hierarchy
There's a hierarchy in our transformations:
- conversion file
- invalid characters
- case conversion
Plus we natively use 2 word separators when parsing the input line: blank (' ') and underscore ('_')
How you set the Invalid Characters behavior is important, as it affects the case conversion behavior. Say, for example that you have camelCase conversion with this Invalid Characters setting:
where a blank (" ") appears in the list of invalid characters (hardly visible, but present in front of the exclamation mark.)
Going through "Customer Account", first we convert the word with the conversion file to "cust acct", then with the Invalid characters config, we remove the blank and get "custacct", but we've lost the word separator, therefore camelCase does not see the "acct" as a separate mode. The end result is: "custacct".
If however, you do a replace blank by underscore:
the sequence becomes "cust acct" then "cust_acct", then "custAcct" which is the expected behavior.
However, it may sometimes be preferable to take the blank (" ") out of the list of invalid characters, and let it be handled by the case conversion.
Choices when applying configuration changes
To better understand the impacts of choices in this dialog:
Let's look at the user cases. It is possible that, during the course of maintaining a model:
- either the model was started with no coupling, then coupling was enabled selectively for some objects;
- or that a model was started with coupling, then coupling was selectively disabled for some objects.
As a result, less than 100% of the objects may have coupling enabled. And it may be on purpose, we have no way to tell.
In such cases, when the choice is being presented as you modify the Naming Conventions parameters, it is important that we apply parameters to objects according to the wish of the user:
- either strictly to the objects for which coupling was previously enabled,
- or give the opportunity to the user to correct an inconsistency, and enable the entire model with the Naming Conventions parameters
You may also perform this operation, without changing the parameters, by clicking the button at the bottom of the Naming Conventions parameters.
Finally, you may also use this button to turn OFF coupling and clear all technical names.