Programming style When to use Caps and Underscores?

[Capt. Quirk]

I have been trying to find a document that explains the Capital letter and Underscore conventions for the standard C18 robot code. To help readability

Thanks

[wt200999]

Are you asking how you should do it or how they have it in the default code?

[Tom Bottiglieri]

I choose something like this:

Variables: Lower case with underscores. Lead with a letter.

int a_variable;

Functions: Lead with lower case letter, change words with caps.

x = getValue(y);

Macros: All caps.

#define    INPUT_A     5

Structures: Start with caps, underscore.
Structure instances: same as variable. (you could make this caps as well)

Motor_Controller left_side;
left_side->sensor = getEncoder(INPUT_A);

[Mike Betts]

The "classic" is the Indian Hill standard. A google of "Indian Hill" will yield hundreds of documents stemming from the IH standard and customized for a particular organization. Here is a good place to start.

[wt200999]

I learned that whatever you do, stick to it. Don't jump around. I.E.

I like to do my variable names like this

int MyVariableName;

other like

int My_Variable_Name;

and I do the same with functions

any kind of #define is always all caps and underscores

I usually see macros as _CAPS

[ay2b]

Use whichever you prefer - just be consistent. The rule for the code at work is "make it match the rest of the file". Asking which to use is like asking any of these other questions:
- tabs or spaces for indenting
- two spaces or four spaces for indenting
- braces on the same line as the conditional or the following line
- "while" on the same line as the closing brase in a do...while or the following line

In other words, it's just a matter of style - use whichever you prefer; the compiler doesn't care. It will help you (and anyone else reading the code) if you are consistent, however. Maybe use underscores for variables and camel case (that's the "capsInTheMiddle") for functions; maybe do the reverse. Just make sure all the code looks the same.

[ay2b]

While it won't help with variable and function names, you might find the program called "indent" useful. It will take C/C++ source code and re-indent it to match your prefered style (as defined by command line switches, or a .indent file). It can modify all the common things that people argue over - tabs vs. spaces, number of spaces, where to put open/close brases, what column to put comments in, what declarations need to be lined up, etc.

(And if you ever work in perl, there's a similar program called "perltidy". I'm sure just about every language out there has such a program - you just have to know what it's called and find it.)

[Guy Davidson]

Note on correct indentation - if you use Eclipse, it can automatically correct indentations in code for you. Makes for much more readable code. I haven't tried it with Python yet, but there it could potentially mess around with things. the joy of Python

As for naming, pick a system that works for you, and to second, third, and fourth everyone else, STICK WITH IT. I usually go ALL CAPS for #define's, and myVariableName style naming for variables and functions.

[Phalanx]

As others have stated there is no "official" style. Again as others have stated pick a style and stick to it. Being consistent throughout is a bigger benefit than it is usually given credit for.

There's an old saying that I found to be true...
"Programmers don't need to spell correctly, just consistently"

What we have opted for is below with a few exceptions.
lower_case_variable_name
UPPER_CASE_DEFINE_MACRO
Mixed_Case_Function_Call()
We indent everything at each level for clarity as well.

We've also adapted a philosophy of modular code design so we can have different programmers working on different functions concurrently and independently. All functions have "Get" and "Set" functions to allow programmers to access values from each function without needing to access a variable directly.

some examples...

#DEFINE ZERO 0
int x = 0;
x = Get_Left_Encoder_Count();
Set_Left_Encoder_Count(ZERO);
if (p1_y == 127)
    {
    pwm01 = 127;
    }
else
    {
    pwm01 = p1_y;
    }

[seanwitte]

I know the question was specifically about C18, but you can use whatever style you want. I think its worth picking a style that can cross multiple platforms, but its up to you. Over the last few years at work we've been moving towards a very simple set of standards that are easy to remember. I'm not a big fan of using prefix notation to add metadata to a variable name. We use c#, but this is a simple convention:

- everything is in CamelCase.
ex) robotSpeed, GetSensorValue(), DoWackyDance()

- private members scoped to a class begin with underscore and lower case.
ex) private int _speed;

- parameters begin with a lower case letter
ex) public int GetSensorValue(int sensorPort)

- property, method, class, and interface declarations start with upper case.
- locally scoped variables begin with an lower case letter.
- methods that return a value begin with a verb (i.e GetCredentials())

[Capt. Quirk]

Thank you for all your suggestions.

I was trying to come up with some consciences to use with the kids. In the past I would use the recommendations by Parallax, but they don't quite fit here.

Thanks again

Bill

[11Mort11]

http://www.web-hits.org/txt/codingunmaintainable.html
this should answer your questions

/**/

not really

[billbo911]

Originally Posted by 11Mort11

http://www.web-hits.org/txt/codingunmaintainable.html
this should answer your questions

/**/

not really

OK, I took the liberty to emphasize Alex's joke.

The link is a rather riotous to read if you are in the right mood, and understand it is tongue in cheek. But by all means, DO NOT ACTUALLY FOLLOW THE INSTRUCTIONS FOUND THERE. If you do, it's at your own peril!!


Thanks Alex, that really is a jewel.

[gnormhurst]

Here's where I jump in and preach against the use of naked constants. Use #define <name> <constant> instead.

So instead of

  motorSpeed = 127;

use

#define STOPPED (127) // pwm value for zero speed

...

  motorSpeed = STOPPED;

There are three good reasons for this:

1. It's self-documenting. The macro STOPPED tells the reader what the constant means.

2. If you use a constant more than once and need to change all instances, you only need to change it in one place, instead of searching around for all the '127's in your code that should be changed. And you know you're gonna miss one!

3. The compiler will catch the error in

  motorSpeed = STOPED;

but will not catch

  motorSpeed = 122;

because both 127 and 122 are valid. But "STOPED" is a symbol presumably unknown to the compiler, and it will halt the build and tell you exactly what is wrong: it doesn't understand "STOPED".

Here's my real-life story on this issue. I worked on a project that processed streaming MPEG video in real time. If the code crashed it meant the TV station would go off the air and lose a lot of money.

A line of code checked for a special value indicating a special mode:

  if ( vbv_delay == 0xFFFF )
  {
     ...
  }

This test was performed in several places in my code. The code worked fine for months. One day someone on the project came to me to ask about a crash that looked like it originated in my code. I tracked it down to a typo. One of the tests was

  if ( vbv_delay == 0xFFF )
  {
     ...
  }

Oops. The compiler couldn't help me: 0xFFF and 0xFFFF are both valid constant values.

If I had used

#define VBR_MODE (0xFFFF)

  if ( vbv_delay == VBR_MODE )
  {
     ...
  }

not only would it have been easier to understand by someone else (and the code is now being maintained by someone else) the compiler would have immediately flagged something like

#define VBR_MODE (0xFFFF)

  if ( vbv_delay == VBR_MOD )
  {
     ...
  }

Fortunately we caught this error before we shipped any units, but we were lucky.

The moral: AVOID NAKED CONSTANTS!