Documentation

gitHub

Naming conventions

Note: You may wish to view the how-to video on this subject.

 

Hackolade 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,

 

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:

 

Windows Program Files

Application target: select the target for which these parameters apply

Enable auto-complete: when this option is enabled, auto-completion is active to use the conversion file to type-ahead names as they are created.

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.

 

 

Naming Conventions - apply changes 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:

Naming Conventions - properties

 

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:

Naming Conventions - B2T properties

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:

Naming Conventions - neutral properties

 

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:

Naming Conventions - RE warning

 

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:

Naming Conventions - apply changes with clear

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 NameTechnical Name
Customercust
Accountaccnt
Customer Accountcstacc
Customer Account Centercac

 

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:

Naming Conv - invalid char - remove

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:

Naming Conv - invalid char - replace

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:

 

Naming Conventions - apply changes with clear

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.