Naming Convention - Data Sources (Part 5)

Naming convention is a set of rules for choosing the character sequence to be used for identifiers which denote variables, types, functions, and other entities in code and documentation.

Reasons for using a naming convention*:

• Reduce the effort needed to read and understand code, in addition to enhancing clarity in cases of potential ambiguity.
• Enhance code appearance (for example, by disallowing overly long names or unclear abbreviations) in a way to enhance the aesthetic and professional appearance of work product.
• Help formalizing expectations and promote consistency within a development team.
• Help avoiding "naming collisions" that might occur when the work product of different organizations is combined.
• Provides a meaningful data to be used in project handovers which require submission of program code and all relevant documentation.

Although code is largely hidden from the view of most business users, well-chosen identifiers make it significantly easier for subsequent generations of developers to understand what the code is doing and how to fix or extend the code for new business needs.

For example, although the following:

a = b * c;

is syntactically correct, its purpose is not evident. Contrast this with:

weeklyPay = hoursWorked * payRate;

which implies the intent and meaning of the code, at least to those familiar with the underlying context of the application.

Again, you still can write the best program without following any naming convention, but yet if you want to have that cherry on your cupcake (and sometimes it’s the icing) you need to follow some self-documenting methods to accomplish that. There are many ways to do so, and here I lay down to you some of them, in case you have no idea what to use, however keep in mind that the sky is your limit, you can come up with your own naming convention as long as it works, and proven it’s a good practice.

First of all let’s introduce available naming styles:

1. Pascal casing (GetSubscriberNumber) the first letter of each word is capital.
2. Camel casing (getSubscriberNumber) the first word/verb is small then the first letter of each word is capital.
3. All caps (GET_SUBSCRIBER_NUMBER) all letters are capital, notice that in this case we are obliged to use a separator.

Data Sources (Database Tables, Columns and Stored Procedures Naming)

Tables

• Use all caps.
• Use plural, only for the entity the table is referring to. E.g.:

1. CUSTOMERS: a collection of customers whereas one row refers to a customer entity.
2. CUSTOMER_ORDERS: a collection of orders whereas one row refers to an order entity made by a customer.
3. CUSTOMER_ORDER_ITEMS: a collection of items, whereas one row refers to an item that’s related to an order that’s in turn related to a customer.

     Notice that using this, allows to relate different main foreign keys that builds up your table, which makes your table not only self-descriptive but also business descriptive.

• Use the underscore (_) as a separator.
• Never use Hungarian notation.

// Bad Practice

Customer

tblCustomer

CustomerTable

Customer Orders

// Good Practice

CUSTOMERS

CUSTOMER_ORDERS

PAYMENT_CRITERIAS

• Avoid using abbreviations unless the name is too long.

// Bad Practice

SUBCR_ADDRESSES

// Good Practice

SUBSCRIBER_ADDRESSES

• Use database schemas when defining tables, however use Pascal casing for schemas.

// Example

Security.USERS

Security.USER_IN_GROUPS

Security.GROUPS

OrderManagement.CUSTOMER_ORDERS

OrderManagement.CUSTOMER_PROFILES

OrderManagement.CUSTOMER_ORDER_ITEMS

Columns

• Use Pascal casing.
• Avoid using all caps (exceptions: ID, medical abbreviations, etc…).
• Never use separators in columns naming.
• Again, avoid using abbreviations unless the name is too long (exceptions: common abbreviations, medical abbreviations, banking abbreviations, etc…).
• Never repeat the name of the table, nevertheless if the column is a foreign key then it’s a must to add the table name as singular.

// Bad Practice (CUSTOMERS table)

CustomerID

CustomerFirstName

CustomerAddress

// Good Practice (CUSTOMERS table)

ID

FirstName

Address

// Good Practice (CUSTOMER_ORDERS table)

CustomerID (foreign key from CUSTOMERS table)

• For bit value columns (Boolean) use a question prefix like Can, Is or Has.

// Bad Practice

Deleted

Add

Values

// Good Practice

IsDeleted

CanAdd

HasValues

Stored Procedures

• You can use different naming styles for your stored procedures, however the naming format is the same for all, which is singular – instead of plural – table name then operation (Insert or Add, Update or Edit, Select or Get and Delete):

1. Mixed, all caps and Pascal casing, whereas the table name is all caps while the operation is Pascal casing – I recommend this technique – (e.g. CUSTOMER_Insert, CUSTOMER_OERDER_Update, CUSTOMER_ORDER_ITEM_Delete, CUSTOMER_PROFILE_GetAll).
2. All caps (e.g. CUSTOMER_INSERT, CUSTOMER_OERDER_UPDATE, CUSTOMER_ORDER_ITEM_DELETE, CUSTOMER_PROFILE_GET_ALL).
3. Pascal casing (e.g. Customer_Insert, CustmerOrder_Update, CustomerOrderItem_Delete, CustomerProfile_GetAll).

• Notice that we have two naming for the same operation, however never mix namings, stick with one operation naming convention; for example use either Add or Insert, but never use both.
• Never use procedure operation in the beginning, again first table name then operation.

// Bad Practice

GetAll_CUSTOMER

GetAll_CUSTOMER_ORDER

Update_CUSTOMER_PROFILE

Update_CUSTOMER_ORDER_ITEM

// Good Practice

CUSTOMER_GetAll

CUSTOMER_ORDER_GetAll

CUSTOMER_PROFILE_Update

CUSTOMER_ORDER_ITEM_Update

• Never use “select *” other than being not self-documenting, this causes quite a performance issue, where “select *” query’s the table data rather than accessing the data from indexes.
• In case you are doing an operation that involves foreign keys parameters then include both primary key(s) (if it’s part of your query) and foreign key(s) while naming (this rule applies only for insert, update and delete operations).

// Bad Practice

CUSTOMER_DeleteByID

CUSTOMER_UpdateByID

// Good Practice

CUSTOMER_DeleteByIDAndStateID

CUSTOMER_UpdateByStateID

• When naming get (select) producers, list all expected parameters to be passed in your procedure naming, nevertheless if you are passing more than three parameters, try to come up with a name that describes the business meaning of your procedure. However, if there are no parameters to be passed, name the operation “GetAll” or “SelectAll”.

// Bad Practice

CUSTOMER_Get

CUSTOMER_GetWithParameters

CUSTOMER_GetWith4Parameters

CUSTOMER_GetWith4Parameters_Updated

// Good Practice

CUSTOMER_GetAll

CUSTOMER_GetByID

CUSTOMER_GetByIDandFirstName or CUSTOMER_GetByID_FirstName

CUSTOMER_GetByIDFirstNameAndLastName or CUSTOMER_GetByID_FirstName_LastName

CUSTOMER_Search

CUSTOMER_AdvancedSearch

• In case you are doing a procedure that contains join(s) – which will not return values from one table – again try to give the procedure a business meaning when naming it (e.g. CANCELLED_CUSTOMER_ORDERS_GetAllByMonth, CUSTOMER_ORDERS_WITH_BLOCKED_PAYMENTS_GetAllByDate).\
• Again, avoid using abbreviations unless the name is too long (exceptions: common abbreviations, medical abbreviations, banking abbreviations, etc…).

Continue Reading (Part 6) >>>

(*) Wikipedia – Naming Convention (Programming)