Five Good Reasons to Name your Fields Correctly

People will start to believe that I am starting a series on agriculture (see my previous post: Name your fields, it’s easier when you’re gonna harvest).

They would be partially wrong. I don’t only want to normalize field naming, I also want to normalize tables, columns, databases, indices, keys, and more at the application level.

This way, we can focus solely on the business logic instead of being bothered with the housekeeping stuff.

Ognjen Orel
IT Specialist at the University of Zagreb (Croatia), Secretary at Adria IUG

 

I have been passionate about normalization, conventions and rigor in project management. At least in the naming (for now).

I have been debating this issue with a few friends and I wanted to share their thoughts with you in this few lines.

Good Reason #1: Everybody can Communicate more Easily about Databases (and more)

When elements (tables, columns or even databases in larger projects) are named consistently, it is easier to communicate around them.

The invoice table is containing invoices. The invoice.shipping_date is the shipping date of this invoice. The invoice.date column is the date when the invoice was established. Concise, self-explanatory.

Eric Vercelletto, an IBM Champion and database specialist out of Pont l’Abbé (France), points out:

Object naming is an agreement in your company or wider than that, that has to allow project stakeholders to understand the purpose of those objects and the code related to them.

Harvey Wigfall, a senior technical analyst at Celanese in Dallas, TX (USA) confirms that “for engineers, developers, database administrators, and architects, establishing a standard and consistency in object naming, provides a hint of the object purpose, usage, and relation to other objects and helps understanding the application and database environments”.

Good Reason #2: Increase Developers Productivity

As Ognjen said, developers will be more productive as they will focus on the business logic. If you use ORM tools like Hibernate or Apache Torque the resulting Java naming of the POJOs and methods will not required documentation. I used a Java example but it is true for any other language.

Code maintenance will also be cheaper, as a direct consequence.

Good Reason #3: Other Tools will Love You

Erik Stahlhut, from Cursor Software AG, an IBM technical distributor in Kassel (Germany) is convinced that it is more cost effective to use proper naming for building reports:

If you access the table with BI-tools like Cognos to create reports, it´s much easier and it reduces time and costs. No need to translate cryptic table names. In the past, I spent many hours to find out which table in “Baan” contains the needed information and referential constraints.

Good Reason #4: It Pays Off

It takes time to set up a convention. As management is looking for quick turn-around, it may see this part of a project as a waste of time. However, as Borut Hadžialić, a software development consultant at Commerzbank AG out of Frankfurt Am Main (Germany), rejects this argument:

Spending time on naming things well always pays off – as the names are read many, many times, and when the names can document (a big part of) the intentions and design of your code/architecture, then the time spent on naming pays off through permanent increased understandability. And understanding is always a prerequisite of making any changes or progress.

Good Reason #5: Documentation is Cheaper to Maintain

We could almost think that we do not need documentation anymore, right? This is an extreme scenario… But how many projects have you been working on where documentation is not up-to-date or lost or on a wiki we lost the access credentials or gone with the developer who retired last month or…

Harshit Shrivastava, assistant manager at Zeuron Systems in Bangalore (india):

From a developer’s point of view, smart nomenclature helped us in understanding the whole database very easily. Lack of thorough documentation was compensated by a proper and logical nomenclature of tables, columns and linked queries. We were able to enhance the application without any of the original developers involved, which saved a lot of time.

Good Practices

So is there some good practice or bad practice to follow or avoid?

Eric adds “There is no point in prefixing a table name by ‘t_’ or ‘tbl’ because the syntax knows it is a table (else your developer has a knowledge problem). Same for indexes: there is no point in calling it ‘idx_xxx’, because when you handle it, you know it is an index. Nonetheless, it is important to know it is a unique index ‘iu_’ or duplicate ‘id_’, or a primary key index ‘ipk_’ or foreign ‘ifk_’”.

Field prefixes are also not very useful user.user_id or user.usr_fname are indeed speaking to everyone, but I would rather see user.id and user.first_name: they carry the same weight.

As Robert C. Martin points in his book “Clean Code: A Handbook of Agile Software Craftsmanship”:

The hardest thing about choosing good names is that it requires good descriptive skills and a shared cultural background. This is a teaching issue rather than a technical, business, or management issue. As a result many people in this field don’t learn to do it very well.

Do not underestimate the power of culture, specially as, in those days, teams are spread all around the world, even for small scale projects.

Consistency

Whatever the reasons are for setting a naming convention, it should take into account the existing projects, databases, rules, and habits of your IT team.

Evolution yes. Revolution no. But this is probably the subject of another article.

 

Special thanks to Eric Vercelletto, Ognjen Orel, Erik Stahlhut, Borut Hadžialić, Harvey Wigfall, Harshit Shrivastava, and others (who wanted to remain discrete) who helped me write this article.

 

Further reading:

• “Clean Code: A Handbook of Agile Software Craftsmanship” by Robert C Martin, Chapter 2 “Meaningful Names”.