Improving variable names in a dataset

Question

Good variable names are:

a) short / easy to type,

b) easy to remember,

c) understandable / communicative.

Am I forgetting anything? Consistency is something to look for. The way I would put it is that consistent naming conventions contribute to the qualities above. Consistency contributes to (b) ease of recall and (c) understandability, though other factors are often more important. There is a clear tradeoff between (a) name length / ease of typing (e.g. all lowercase) and (c) understandability.

I'm investing a fair bit of thought in these issues because thousands of people are using the data and I hope many will use my code to prepare the data and facilitate some types of analysis. The data, from the Longitudinal Study of Adolescent Health, is broken down into multiple datasets. My first step was to take the 227 variables in the most commonly used dataset, recode them, give them more meaningful names. Original variable names are things like "aid", "s1", "s2", which I renamed "aid2", "age", and "male.is". There are thousands of other variables in the other datasets which may be merged depending on what the researcher's goals are.

As long as I'm renaming variables, I want to make them as useful as possible. Here are some of the issues I've considered. So far, I have only used lower-case and avoided using any dashes or underscores, and I've only used periods for one very specific purpose. This has the virtue of simplicity and consistency, and causes no problems for most variables. But as things get more complex I'm tempted to break my consistency. Take, for example, my variable "talkprobmsum", it would be easier to read as "talkProbMSum" or better still "talk.prob.m.sum", but if I'm going to use capital letters or periods to separate words then shouldn't I do it for all variables?

Some variables are recorded at more than one time, e.g. the race variables so I appended .is or .ih to indicate whether they come from the in-school or in-home questionnaire. But there are surely some repeats I'm not aware of yet, would it be better to append a reference to the dataset to the name of every variable?

I need to group-center and standardize a lot of variables, the way I've done that is by appending .zms meaning z-score by male and by school.

Any general or specific thoughts or resources are greatly appreciated. See this repository for some of my code, and descriptive statistics with a list of variable names. I briefly described the reason for sharing this code here, and it was publicized a bit here, but these last two links aren't really relevant to the issue of variable naming conventions. Added: I edited this lightly, mostly just moving a paragraph, to try to avoid some of the confusion evident in the comments. Thanks for thoughts!

Added 2016-09-05: Its worth noting Hadley Wickham's R Style Guide and Google's R Style Guide... Hadley says:

Variable and function names should be lowercase. Use an underscore (_) to separate words within a name.

Google says:

Don't use underscores ( _ ) or hyphens ( - ) in identifiers. Identifiers should be named according to the following conventions. The preferred form for variable names is all lower case letters and words separated with dots (variable.name), but variableName is also accepted; function names have initial capital letters and no dots (FunctionName); constants are named like functions but with an initial k.

Answer 1

The best response to this question is to duck it. Fundamentally, it doesn't much matter what the short names of the variables are as long as they are well documented in a codebook somewhere. Alas, since R has no native resources for this, people tend not to bother. (The lack is, for me, the single biggest failing in the language as a statistical tool).

There are various R packages providing this machinery, e.g. Hmisc which you use, and memisc. But really the best option is to make the whole thing into an R package. That way the processed data can be an object with a corresponding help page that describes what everything is now called and can assign credit where it's due. The package can also expose the raw data and your processing functions for people to see what you did to make the final product.

Also, a suggestion: don't include derived data like variables and their z-scored versions in the final data object at all if you can help it, just provide the functions to make it instead. Derived data is just trouble from the data management point of view.

Answer 2

Here's a small thing: I think it's better to use underscores than periods. The reason is that most programming languages, unlike R, don't support periods in identifiers, but nearly all support underscores. And I presume you want your dataset to be useful to people who aren't using R.

Answer 3

First of all, thank you for doing this - I'm sure many people will appreciate it, even though not many will know that you did it.

RStudio user interface does not (at least with default options?) interpret any separators within variable name. For example, Eclipse treats capitalized parts as separate words, so you can use Ctrl+arrows to quickly edit Java-style code like ageStandardizedMaleSchool. I can't come up with any better reasons to prefer one separator over another, so either underscores or caps seem fine to me.

In general, I suggest making the variable names longer, rather than sticking to some complex abbreviation scheme. It is easy to make typos like talk.prob.m.sum instead of talk.prob.sum.ms, and it's difficult to spot and trace errors in statistical analysis. (Somewhat related: a nice saying I've read on some blog is to write your variable names like Scandinavian words - SickHouse and ToothHealer instead of hospital and dentist.)

On a final note: standardizing, centering etc. are generally done after data cleaning. If there's no cleaning, then maybe consider leaving that to whoever will analyze the data. Or, if you're doing the cleaning yourself as well, indicate all the steps you've taken - subsequent analyses and interpretations might depend a lot on that.