Naming variables and functions

An important aspect of programming that I never paid much attention to is the naming of things such as variables and functions. I think the reason is because a script/program will work as long as the syntax is correct and the naming of things is unimportant to the computer. When I first learned programming as a bioinformatics student, I just wanted my scripts to work so that I could produce results for my thesis. Code readability was not a priority and besides I could still remember the logic of my scripts because I was actively working with them. And because I was always focused on the results, I neglected many things that are important in software engineering such as the naming of variables and functions.

Programming languages typically let you use any name you want with just a few restrictions. For example in R, object names must start with a letter and can contain only letters, numbers, underscores (_), and periods (.). Python has reserved words that cannot be used as identifiers like True and if you try to assign a string to it, you'll get the following error:

    True = "Paul Pierce"
    ^^^^
SyntaxError: cannot assign to True

Aside from these restrictions, programmers can create names any way they like and this flexibility can create problems. Therefore the first tip to naming things is to limit the possibilities by adhering to a consistent style. For example, pick a particular casing style and stick to it:

snake_case = "lowercase letters separated with _"
kebab-case = "same as snake case but with -"
camelCase = "start with lowercase and capitalise next word/s"
PascalCase = "same as camel case but capitalise all words"

As an aside, some programming languages have different preferences. For example snake case is preferred in Python and camel case in Java. I think it's better to stick to the convention if you are programming in a language that has a preference. If there isn't a known preference like in R, pick a style guide like the tidyverse style guide and stick to it. Importantly, as stated in the tidyverse style guide:

All style guides are fundamentally opinionated. Some decisions genuinely do make code easier to use (especially matching indenting to programming structure), but many decisions are arbitrary. The most important thing about a style guide is that it provides consistency, making code easier to write because you need to make fewer decisions.

As I pointed out at the beginning, programming languages are really meant for people and not machines. Ultimately, as long as the code compiles/assembles into machine code, the machine "doesn't care". Therefore creating readable code is really just for our benefit in understanding and maintaining the code. The naming of things has a lot of inherit meaning when read by a human. Therefore it is important to carefully pick names!

As pointed out in The Pragmatic Programmer and paraphrased here, things should be named according to their purpose in your code. To ensure this, you should stop and ask yourself "what's the motivation for creating this?" when creating a new variable or function. This is an important exercise because not only do you stop and think, it also brings you back to the bigger picture of what your code is trying to achieve. I tend to get tunnel-visioned when working on a problem and it's important to reset from time to time to remember the overall question that I was trying to answer.

In summary, when naming variables and functions:

1. Be consistent, which can be achieved by following a style guide
2. Stick to the convention used in your programming language of choice
3. Come up with names that convey the purpose of your variable or function

Remember that source code is meant for humans, unless you are coding in machine code in which case I question your humanity.