A Virtualized Way to Describe the Naming Convention

Introduction

In this tip, I would like to take a few minutes to share my opinions about the naming convention. Sometimes members in the team have different views, habits and skill levels and it could cause a situation that everybody is reluctant to follow the same rules. Therefore, naming convention could actually affect the atmosphere in the group.

We all know that there is no perfect rule existing in the world: everything is relatively good or bad. But there could be a better method to build the convention. So in the following sections, I will explain on a virtualized, mathematical way to determine whether a set of naming rules is suitable or not that suitable for the programming language that you are using.

Terminologies

Before we start talking about our subject, there are a few terminologies that I would like to introduce first. These terminologies will be widely mentioned in this tip. 

Language Convention

This is the convention that is recommended by language designers and performs in the most common library of a language. For example, C++ has STL, C# has .NET Framework Class Library, Java has Platform Standard. You can easily discover the rule from each of them that is followed by its members. 

Team Convention

This is the convention that is followed by your team members and your own libraries/code. For example, a company would set the first word of .NET Framework namespace with their name. Teams that belong to the company should follow this rule to name the namespace in their product.     

Set

Set is a mathematical concept discussed in set theory that is a collection of distinct elements. In this article, element is described as a rule, and a set, of course, is the naming convention formed by number of rules. A bigger set could be described a naming convention consisting of more rules to restrict the code.

The Relationship Between Sets

Since we have two "sets": the language convention and team convention, we can start taking a deeper look at the relationship between them. In this section, we use the naming rules for interface in C# as an example of language convention. It can be summarized with the following quote:

Language Convention:

Interfaces should follow the Pascal case and have prefix of letter I. (e.g. ICollection) 

Obviously, there are two rules in this convention:

1. The Pascal case
2. The prefix with letter I

Regarding the interface, the relationship between your team convention and it could be one of following figures:  

The language convention is the subset of your team convention.

In this type of relationship, your team convention is developed based on the language convention. The team convention includes and provides more rules than language convention, as Figure 1 shows below:  

Figure 1

Here is an example:

Team Convention 1:

Interfaces should follow the Pascal case and have prefix of letter I. Interface for unit testing should end with keyword UT. (e.g. IOurGameCollectionUT)

This convention provides Pascal case and prefix letter rules, which are in common with language convention. But it also provides another "Interface for unit test" rule to restrict interface naming further.

The language convention intersects your team convention. 

In this type of relationship, your team convention is partially derived from language convention, and partially incompatible with latter. The relationship is shown in Figure 2:

Figure 2

Here is an example:

Team Convention 2:

Interfaces should follow the Pascal case and have prefix of keyword Our. (e.g. OurGameCollection)

As you can see, both conventions have "follow the Pascal case" rule in common, but the prefix rules are conflicting. Therefore, the relationship between them is intersection.

The language convention is disjoint to your team convention.

In this type of relationship, your team convention does not refer to language convention. Rules are entirely incompatible with the latter, as Figure 3 shows below:

Figure 3

For instance:

Team Convention 3:

Interfaces should follow the Camel case and have prefix of keyword our (eg. ourGameCollection).

In this example, we have two rules (casing and prefix) and both of them are all conflicting with language convention. Accordingly, they are disjoint to each other.

Review Your Naming Convention

So, you are now able to review your naming convention with a visualized way. Try to take a brief look at your team convention, and draw a simple figure to understand the relationship between both. In any case, you should keep the language convention as the subset of your team convention as much as you can. The reasons are listed below:

1. Language convention is the convention that your teammates are most familiar with. Therefore, team convention that is created based on language convention can help teammates to understand more easily and to get used to.
2. It can keep the style being consistent between your own library and standard library because it is almost impossible to program without referring to the standard library.

Then your team convention could be more suitable for your team.

References

• .NET Framework Naming Guidelines
• Java Code Conventions