best practice for variable names

Hi,

What is the best practice for using variable names? Some questions I have:

When should single letter variable names be used and should they be unique in the code for each single purpose? ie can ‘i’ be used in different calculations in different parts of the sketch

Sometimes I see the variable type defined in the code rather than at the top of the sketch, when is this appropriate or not appropriate?

eg:

for (byte i = 0; i < NUM_LEDS; i++)  
  {

  }

In a sketch with multiple objects, should variable names be unique within the whole sketch or can the same variable names be used in different classes?

If there are any guides to best practice that people recommend I would also be very grateful.

Thanks,

Rob

You need to know how to Declaring a variable and the scope of the variable.

int gPWMval;  // any function will see this variable

void setup()
{
  // ...
}

void loop()
{
  int i;    // "i" is only "visible" inside of "loop"
  float f;  // "f" is only "visible" inside of "loop"
  // ...

  for (int j = 0; j <100; j++){
  // variable j can only be accessed inside the for-loop brackets
  }

}

BillHo:
You need to know how to Declaring a variable and the scope of the variable.

int gPWMval;  // any function will see this variable

void setup()
{
  // …
}

void loop()
{
  int i;    // “i” is only “visible” inside of “loop”
  float f;  // “f” is only “visible” inside of “loop”
  // …

for (int j = 0; j <100; j++){
  // variable j can only be accessed inside the for-loop brackets
  }

}

Thanks, your example makes perfect sense now. I’ve read those pages before but obviously something didn’t click!

With regards to my second question:

In a sketch with multiple objects, should variable names be unique within the whole sketch or can the same variable names be used in different classes?

I can assume that it’s OK to reuse the same variable names then as they wont be accessible by different objects unless they are declared globally?

Actually I don't think i'd read the 'scope' page before which is exactly what I needed! Thanks

dillonradio:
When should single letter variable names be used

Single letter variable names are only appropriate very localy. So like for example in a for loop or a small function like

int addValues(int a, int b){
  return a + b;
}

At global level they are a big no go. Better to have a longer and self explaining variable name the a short and cryptic one like "output". In the end the longer one is even easier to remember because it's not cryptic.

dillonradio:
and should they be unique in the code for each single purpose? ie can 'i' be used in different calculations in different parts of the sketch

They should be unique in there scope or otherwise you can only work with the local variable.

Exception is with the global scope. You could use a local variable with the same name as a local variable and use the global scope resolution :: . But that makes code harder to read so is considered bad practice.

dillonradio:
Sometimes I see the variable type defined in the code rather than at the top of the sketch, when is this appropriate or not appropriate?

That is always preferred! You should declare a variable as local as possible. It's nonsense to declare a variable at local scope if you just use it in one of your functions. So only variables that need to be accessable everywhere in the code (like a pin definition, a general mode of he program etc) or a constant (const) like a setting (a timeout or something) is okay the make global (aka, define at the top). Otherwise, define where needed. And yes, this is lacking in the programs of most beginners. They tend to make all variables global (and int for that matter...)

dillonradio:
In a sketch with multiple objects, should variable names be unique within the whole sketch or can the same variable names be used in different classes?

You can use the same variable name in different classes. Because then they are unique in there scope namely the class. Or even more precise, unique in there object. Because you van make multiple objects of a class that all have a variable myInt. Otherwise a object would be useless if they can't all have a variable with different content.

dillonradio:
If there are any guides to best practice that people recommend I would also be very grateful.

Yes, clear and descriptive names, not short names.

Define them as local as possible. So read about variable scope :wink:

And write a variable name like myVariableName (starting with a small letter and every new word in it with a capital), not myvariablename of my_variable_name. It's not an error but considered best practice.

And some (like I) like to make clear we're dealing with a constant by the using a name line MyConstVariableName. The starting capital is a reminder it's a const and we can't change it.

Use the smallest variable type that suits your need. (No need to define a pin as int, a byte is big enough).

You can use the same variable names as long as their in different scope and not visible each other.

Serial.print("Hello world.");

lcd.print("hello, world!");

both have the same print() function with the same names.

That’s amazing, thanks!

Rob

septillion:
Single letter variable names are only appropriate very localy. So like for example in a for loop or a small function like

int addValues(int a, int b){

return a + b;
}



At global level they are a big no go. Better to have a longer and self explaining variable name the a short and cryptic one like "output". In the end the longer one is even easier to remember because it's not cryptic.
They should be unique in there scope or otherwise you can only work with the local variable.

Exception is with the global scope. You could use a local variable with the same name as a local variable and use the global scope resolution :: . But that makes code harder to read so is considered bad practice. 
That is always preferred! You should declare a variable as local as possible. It's nonsense to declare a variable at local scope if you just use it in one of your functions. So only variables that need to be accessable everywhere in the code (like a pin definition, a general mode of he program etc) or a constant (const) like a setting (a timeout or something) is okay the make global (aka, define at the top). Otherwise, define where needed. And yes, this is lacking in the programs of most beginners. They tend to make all variables global (and int for that matter...)
You can use the same variable name in different classes. Because then they are unique in there scope namely the class. Or even more precise, unique in there object. Because you van make multiple objects of a class that all have a variable myInt. Otherwise a object would be useless if they can't all have a variable with different content.
Yes, clear and descriptive names, not short names. 

Define them as local as possible. So read about variable scope ;)

And write a variable name like myVariableName (starting with a small letter and every new word in it with a capital), not myvariablename of my_variable_name. It's not an error but considered best practice. 

And some (like I) like to make clear we're dealing with a constant by the using a name line MyConstVariableName. The starting capital is a reminder it's a const and we can't change it.

Use the smallest variable type that suits your need. (No need to define a pin as int, a byte is big enough).

septillion:
Single letter variable names are only appropriate very localy. So like for example in a for loop or a small function like

int addValues(int a, int b){

return a + b;
}



At global level they are a big no go. Better to have a longer and self explaining variable name the a short and cryptic one like "output". In the end the longer one is even easier to remember because it's not cryptic.
They should be unique in there scope or otherwise you can only work with the local variable.

Exception is with the global scope. You could use a local variable with the same name as a local variable and use the global scope resolution :: . But that makes code harder to read so is considered bad practice. 
That is always preferred! You should declare a variable as local as possible. It's nonsense to declare a variable at local scope if you just use it in one of your functions. So only variables that need to be accessable everywhere in the code (like a pin definition, a general mode of he program etc) or a constant (const) like a setting (a timeout or something) is okay the make global (aka, define at the top). Otherwise, define where needed. And yes, this is lacking in the programs of most beginners. They tend to make all variables global (and int for that matter...)
You can use the same variable name in different classes. Because then they are unique in there scope namely the class. Or even more precise, unique in there object. Because you van make multiple objects of a class that all have a variable myInt. Otherwise a object would be useless if they can't all have a variable with different content.
Yes, clear and descriptive names, not short names. 

Define them as local as possible. So read about variable scope ;)

And write a variable name like myVariableName (starting with a small letter and every new word in it with a capital), not myvariablename of my_variable_name. It's not an error but considered best practice. 

And some (like I) like to make clear we're dealing with a constant by the using a name line MyConstVariableName. The starting capital is a reminder it's a const and we can't change it.

Use the smallest variable type that suits your need. (No need to define a pin as int, a byte is big enough).

Hi I have one further question, which regards variable names used to work with BlinkWithoutDelay IF statements. If I have currentMillis and previousMillis as my variable names to simulate delay in one part of an object, should I use different variable names to do another delay simulation in a different part of the same object?

Thanks

dillonradio:
If I have currentMillis and previousMillis as my variable names to simulate delay in one part of an object, should I use different variable names to do another delay simulation in a different part of the same object?

When I write a program the variable currentMillis is usually global and is update at every iteration of loop(). It provides a single consistent value for millis to be used throughout that iteration - perhaps in several functions.

Whether you use the variable previousMillis more than once depends on whether two actions should depend on the same value. That is probably unlikely.

Have a look at Planning and Implementing a Program. I am a great believer in meaningful names for functions and variables. I aim (and often fail) to write code that I can understand 6 months later after a single read-through.

I am not particularly precious about global versus local variable names in the small memory space of an Arduino.

I would caution strongly against deliberately (or accidentally) using the same variable name in different scopes. IMHO it is a guarantee for confusion.

...R

dillonradio:
Hi I have one further question, which regards variable names used to work with BlinkWithoutDelay IF statements. If I have currentMillis and previousMillis as my variable names to simulate delay in one part of an object, should I use different variable names to do another delay simulation in a different part of the same object?

Well, here is my slant on that one:

// Blink without "delay()" - multi!

const int led1Pin =  13;    // LED pin number
const int led2Pin =  10;
const int led3Pin =  11;

int led1State = LOW;        // initialise the LED
int led2State = LOW;
int led3State = LOW;

unsigned long count1 = 0;   // will store last time LED was updated
unsigned long count2 = 0;
unsigned long count3 = 0;

// Have we completed the specified interval since last confirmed event?
// "marker" chooses which counter to check 
boolean timeout(unsigned long *marker, unsigned long interval) {
  if (millis() - *marker >= interval) { 
    *marker += interval;    // move on ready for next interval
    return true;       
  } 
  else return false;
}

void setup() {
  pinMode(led1Pin, OUTPUT);      
  pinMode(led2Pin, OUTPUT);      
  pinMode(led3Pin, OUTPUT);      
}

void loop() {
  // Act if the latter time (ms) has now passed on this particular counter,
  if (timeout(&count1, 500UL )) {
    if (led1State == LOW) {
      led1State = HIGH;
    }
    else {
      led1State = LOW; 
    } 
    digitalWrite(led1Pin, led1State);
  } 

  if (timeout(&count2, 300UL )) {
    if (led2State == LOW) {
      led2State = HIGH;
    }
    else {
      led2State = LOW; 
    } 
    digitalWrite(led2Pin, led2State);
  } 

  if (timeout(&count3, 77UL )) {
    if (led3State == LOW) {
      led3State = HIGH;
    }
    else {
      led3State = LOW; 
    } 
    digitalWrite(led3Pin, led3State);
  } 
}

Note the use of three individual "count" variables, which are passed by pointer to the generic "timeout" function to determine the corresponding individual timing events.

Google "Google coding standards"

Note the use of three individual "count" variables,

To me that cries out for arrays and a for loop to be used.

#define GREENSWITCH // when using define, it is customary to use all caps. you can identify it in the code that way.
#define GREEN_SWITCH_TWO

adafruit uses define in almost all sketchs.
not sure if that offers more cross platform use of code

since capitalization it is not required in the arduino IDE, you will find a lot of people who do not follow that convention.

trivial note :
in the old Fortran, variables that began with i,j,k,l,m and n are integers and you did not have to declare them as integers
the other letters defaulted to single precision real numbers, but you could add a declaration to anything to make it specific for your use.

dave-in-nj:
trivial note :
in the old Fortran, variables that began with i,j,k,l,m and n are integers and you did not have to declare them as integers

I always wondered why these letters were typically used that way. I thought it was something to do with i and n often being used in maths equations.

septillion:
That is always preferred! You should declare a variable as local as possible. It’s nonsense to declare a variable at local scope if you just use it in one of your functions. So only variables that need to be accessable everywhere in the code (like a pin definition, a general mode of he program etc) or a constant (const) like a setting (a timeout or something) is okay the make global (aka, define at the top). Otherwise, define where needed. And yes, this is lacking in the programs of most beginners. They tend to make all variables global (and int for that matter…)

you can’t really blame beginners.
naming is slang and shorthand and just plain not well defined.

in this program
int led = 1;
void setup{}
void loop{
digitalWrite(led,HIGH)
}
what is the technical name for the space allocated to declare led ?
that space before void setup() ?

how do you declare led in this version ?
void setup{}
void loop{
digitalWrite(led,HIGH)
}

==========================
how about this one ?

void setup{}
void loop{
if (keySwitch1 == LOW){
digitalWrite(led,HIGH)
}
if (keySwitch2 == LOW){
digitalWrite(led,LOW)
}

// turn off led
digitalWrite(led,HIGH)

} // end void loop

in most beginner sketchs, the scope is all local to one thing.

===============================================

it is often stated that the variable be as local as possible.
but there is no mention in the links for scope or variable that helps a beginner to know that ‘local’ means

also, there is repetitive notes about changing a variable in other places…
would you want to write a program like this ?

void setup{}
void loop{
if (keySwitch1 == LOW){
int led 2; // declares led for pin 2
digitalWrite(led,HIGH)
}
else
{
digitalWrite(led,LOW)
}
if (keySwitch2 == LOW){
int led 3; // declares led for pin 3
digitalWrite(led,LOW)
}
else
{
digitalWrite(led,HIGH)
}

} // end void loop

==========================================================
as for understanding a sketch, declaring values locally are confusing.
if ( int key_switch = HIGH){
digitalWrite( int LED 2, HIGH )
}
else
{
digitalWrite(LED,LOW )
}

if you are telling me I have to declare these on a separate line and not inside of the function, then why can I write this
for (int i=0; i <= 255; i++)
and if one has to write them on separate lines, why not just put them in one place for easier housekeeping ?
as a beginner, one has to fight just understanding the few lines of code. All the additional bits get confusing.
if you want say that in my examples, the references should be constants… then you are just layering on the complexity.
I would offer that in almost every case of my attempts to use the references or learning tabs to find out how to do a thing, I get the very minimum information. a couple links at the end, for beginners, intermediate, advanced, would allow one to open the beginner tab and get an explanation of how it works, on the advanced tab, additional use or adaptions, intermediate would be, well, just that.
if you want, you could make them baby bear, momma bear and pappa bear.

dillonradio:
I always wondered why these letters were typically used that way. I thought it was something to do with i and n often being used in maths equations.

whomever wrote the program must have figured that allowing a simple way to have the software declare if they were integers or real numbers without having to spell it out was easier.
when I learned Fortran, it was very easy for me, best in my class and would punch out my cards, then help others before the end of the period. I think that there was one less thing to remember helped.
it would be easier for all of us if
RED_LED was global
redLed was local.
alas, we all come from so many starting points, I doubt if we will ever all agree.

@dave-in-nj, you forgot the code tags in Reply #14.

Forum Best Practice :slight_smile:

...R

dillonradio:
I thought it was something to do with i and n often being used in maths equations.

It was, and still is. Fortran is, quite literally, for FORmula TRANslation.

robin2:
@dave-in-nj, you forgot the code tags.

Caps, too. Speaking softly, I guess. :wink:

Robin2:
I am not particularly precious about global versus local variable names in the small memory space of an Arduino.

I would caution strongly against deliberately (or accidentally) using the same variable name in different scopes. IMHO it is a guarantee for confusion.

Thanks for this advice, but at the moment it seems my list of global variables is spiraling out of control and I can see the value of making some of them a bit more local.

Quite often though, my variables are used by several functions, one called from inside another. I can see that it might make sense to pass the variables I need from one function to the next. In that case, would I use different variable names in the second function? It might make it confusing if I start giving the variable a second name when it is essentially the same data.

I posted a similar question in my LED thread so apologies for duplication, I realised that it was a better question for this one.

Responding to Reply #18.

I am certainly not opposed to local variables.

Ideally a function is very short - perhaps 5 or 10 lines - so that it can all be seen on the screen at one time. In that case the names of the variables within the function can be chosen for convenience.

But I would still ensure that there is no local variable with the same name as a global variable - that is just too confusing for my little brain.

I don't know what is the "proper" way to deal with variables that need to be passed down through several functions, and especially if there are 3 or 4 such variables that "travel" together. I usually wimp-out and make them global. I guess I could create a struct to encapsulate the variables in a single object. But accessing fields within a struct gets very tedious.

...R