embedded software boot camp

Eye, Aye I!

Friday, November 6th, 2009 by Nigel Jones

Today’s post should probably be called ‘Thoughts on non-descriptive variable names’, but once in a while I have to let my creative side out!

Anyway, the motivation for today’s post, is actually Michael Barr’s latest blog posting concerning analysis of the source code for a breathalyzer. Since I do expert witness work, as well as develop products I was keen to see what the experts in this case had to say. One snippet from the expert for the plaintiffs caught my eye. In appendix B of their report, Draeger made the following statement concerning general code issues:

Non descriptive variable names – i, j, dummy and temp

This touched upon something where I seem to be at odds with the conventional wisdom. I’ll illustrate what I mean. Consider initializing an array to zero (I’ll ignore that we could use a library function for this). I would code it like this:

uint8_t buffer[BUFSIZE];
uint8_t i;
for (i = 0; i < BUFSIZE; i++)
{
 buffer[i] = 0;
}

This code would be rejected by many coding standards (and apparently would offend Draeger), as the loop variable ‘i’ is not descriptive. To be ‘correct’, I should instead code it like this

uint8_t buffer[BUFSIZE];
uint8_t buffer_index;
for (buffer_index = 0; buffer_index <BUFSIZE; buffer_index++)
{
 buffer[buffer_index] = 0;
}

So for me, the question is, does the second approach buy me anything – or indeed cost me anything? Well clearly, this is a matter of opinion. However I’d make the following observations:

  1. I think my code is clear, concise and easily understood by even the most unskilled programmer
  2. Is the variable name ‘buffer_index’ clearer – yes but only to a native English speaker. It’s my experience that there are a lot of non-native English speakers in the industry.
  3. Personally, I find the use of similar words in close proximity (buffer[buffer_index]) to be a bit harder to read, and very easy to mis-read if there are other variables around prefixed with buffer.

I’d also make the observation that many coding standards require variable names to be at least 3 characters long, and as a result I’ve seen code that looks like this:

uint8_t buffer[BUFSIZE];
uint8_t iii;
for (iii = 0; iii < BUFSIZE; iii++)
{
 buffer[iii] = 0;
}

Clearly in this case, the person is addressing the letter of the standard (if you’ll pardon the pun), but not the spirit. Where the standard requires the variable names to be meaningful, I’ve also seen this done:

uint8_t buffer[BUFSIZE];
uint8_t idx;
for (idx = 0; idx < BUFSIZE; idx++)
{
 buffer[idx] = 0;
}

This code meets the letter of the standard, and arguably the spirit. Is it really any more understandable than my original code? I don’t think so – but I’ll be interested to get your comments.

Home

Tags: ,

7 Responses to “Eye, Aye I!”

  1. Jonathan Jones says:

    If the code fragment contained multiple array indices it would definitely be better to label each with their function (e.g. DayIdx, HourIdx) instead of using i, j, k…If the code contained even one more scratch variable, say a sum of array values, it would be worth labelling the array index as such to avoid confusion.However as it stands your code is perfectly legible and 'i' is no better or worse than 'idx' in this examples.My preference is to keep variable names short, because I find it makes code more readable.Three more points :-1. This comment is only my opinion. The author of the DSDI report has referred to "Industry best practices". Is there really a global consensus as to what is best practice or should the report author have referenced a specific published standard / labelled it as their (expert) opinion ?2. In Appendix B of the report, it is stated that a conditional of the form "if (x == TRUE)" is better practice than "if (x)". Would you agree ?3. Thanks! I'm finding your posts thought provoking.

  2. Nigel Jones says:

    Jonathon – thanks for your thoughtful comments. I agree that the use of i,j,k can get out of hand. I can't say I've never done this – but it's rare.The concept of 'Industry best practices' is indeed a bit nebulous. There are certainly 'standards' such as MISRA. However, although whereas I'm sure there will not be much disagreement that prototyping functions should be mandatory (and hence could be considered an industry best practice), the same is not true for other things (e.g. casting integers to pointers). I also spotted their claim that the form "if (x == TRUE)" is better than "if (x)". I actually disagree with them. I'll often have variables named thus:bool isFull;I can then write code that reads very naturally:if (isFull){…}If I'm forced into using an explicit comparison, the code becomes:if (isFull == TRUE){…}Now, because this construct is vulnerable to the = / == dichotomy,my coding standard requires that constants appear on the LHS, and so I have to write:if (TRUE == isFull){…}The result is ugly, harder to read and has achieved nothing. Hence I must respectively disagree with DSDI.I'm glad you find the posts thought provoking. Quite frankly one of the reasons I do this is because I in turn find comments such as yours thought provoking! Symbiosis has been achieved!

  3. Darren says:

    I prefer the look of the code implemented with the "uint8_t i" but I think the reason I try to use idx is so that I can search for all occurrences of the variable with a regular text editor, my search results are not polluted with all the appearances of the letter i within the keywords "if", "switch" etc. "uint8_t x" works out a little better from a probabalistic standpoint, but I think the three letter minimum is to encourage meaningful names, and also to prevent false positives in searches.

  4. Kyle Bostian says:

    I think you could make the second example even more clear by adding Hungarian notation into the mix. 🙂 (running and ducking for cover…)

  5. Nigel Jones says:

    I realize that your comment was made in jest Kyle. However I think you do raise an interesting point. A few years ago (OK maybe 10), Hungarian notation was all the rage. I hated it and only used it if mandated by a client's coding standard. Since then the industry seems to have come around to my way of thinking :-). Perhaps the same thing will hold true for loop variable names in a few years!

  6. K1200LT Rider says:

    I'm glad someone else came to the same conclusion as I have about using 'i'. I also agree with Jonathan.Good subject.

  7. Greg Giese says:

    I am fully onboard with the embedded standards but seriously the large variable name for a looping variable in a simple loop is more distracting than useful. As a safety system programmer I would reject such code based on distraction. If i have multiple loops within loops I would demand documentation of the loop vars themselves. If that in itself, causes less clarity in the code then perhaps the coder mis-named the arrays/structures being indexed.

Leave a Reply