Naming conventions and Integration

Interesting reading

Naming conventions, everywhere I’ve been people want them, but are the resulting conventions correct and actually used?

That’s a question I keep asking myself once in a while. Lately even more now that I’m about halfway through “The Programmers Brain” by Felienne Hermans who is a computer science professor and does research in programming education.

While the integration field does not necessarily share all the different problems you might run into with regular programming, one of the omnipresent problems remains - Property naming. Reading the book, I wanted to write down my thoughts on the subject.

Everyone names things differently

In the book Felienne mentions an interesting study from 2021 where Dror Feitelson et al, took a group of 350 subjects and asked them to choose unambiguous names in various programming scenarios. So these could be things like variables, constants, functions and parameters. After the study the result was interestingly that the median probability of people choosing the same name was only 7%. I expected it to be fairly low but not that unlikely. As names of things make up much of any code base, whether that is in programming or low code environments, we should always keep in mind what impact the name of a specific thing can have.

Names as documentation

When reading the code of an existing project I am always first quickly scanning through the names of the various variables and structures that have been defined. Depending on the subject this might even be before checking the actual technical documentation. If it lines up with something that is familiar to me it will be easier to create a good mental model to understand what’s going on. The quality of naming impacts whether this approach is successful quite a lot. But if done right they can serve as “Beacons” to make the code “click” inside my head. Unfortunately there is no universal “Naming quality” standard for everyone. You can use, lowercase, uppercase, CamelCase, snake_case or mixedCase and so on in your code and they are all valid cases. Even then this does not even cover whether the names are unambiguous or not.

Consistency over Quality

When defining names it’s important to keep in mind that the designation being set will have to make sense to other people. Thinking twice about naming something can help prevent a lot of future problems. But this does not always apply. If you’re working in existing project and you feel the naming somewhere is not great, you might feel like “Upgrading” the naming in the newer part you’re adding. I know I have! Unfortunately this will in most cases just exacerbate the issue, in cases like this it makes more sense to keep to the current naming convention, consistency is key. If you are able to find a pattern it will already help a lot to get to understanding. Changing the general naming can be taken up as a larger task in the scope of architectural debt.

New beginnings

Every once in a while you might have the chance to start a completely new project. The great thing heere is that you won’t run into the above issues as you’re first one there and can decide on the naming (If there is no general naming convention defined - which you are hopefully not ignoring). In this case it’s important to keep in mind the power you wield at that moment. Anyone who comes after you will - most likely - copy your naming convention in that project and keep using it, make sure to start in the right way! The same goes for things like comments or tests. People that come after are more likely to copy the style of what is already there instead of actually reading the conventions. This seems to be especially true for github projects, as mentioned in the book the research done by Raphael Pham et al. in their paper “Creating a Shared Understanding of Testing Culture on a Social coding Site” people are much more likely to just copy some part of the project and re-use that as a template than they are likely to read the project guidelines.

What now?

As luck would have it I’m currently in the position where I can define a naming convention. But reading the book and thinking about the research paper conclusions I’ve changed my mind on how i’m going to approach it. Every person has a different interpretation of what is “Best” so I’m first going to take a few projects written by different colleagues and compare the naming styles. Then depending on those results I might meet with a few of them to pick their brain about why they chose the specific conventions which should provide some interesting insight I hope. Afterwards I will compile my thoughts into a naming convention ready to be reviewed by the team.

Meanwhile I will continue reading “The Programmers Brain” I recommend anyone with interest in how memory and other brain functions work in relation to programming to read it. It’s very interesting and does change you perspective a bit on how to best approach different problems. Especially the part about short term memory, long term memory and working memory.