Coding conventions

[Anthony Kesich]

For the past month or so ive been reading the forums at least daily and i've notice one little problem in our programming corener over here; we need some base-line conventions for the ease of people just joining in and people new to programming. I would like to propose a few:

1) If possible, replace pwmXX with some sort of macro throughout the program. That is, instead of putting pwm01 and pwm02, put R_MOTOR and L_MOTOR. Or at least state it at the beginning of your post. More than once, i've been readong code and said to my self, "What the heck does pwm03 do?"

2) We should set down a base-line as to whether we should assume the flipped motor is later software corrected or not (a line at the end of the code somewhere along the lines of R_MOTOR=254-R_MOTOR;). I know last yaer we did just because the default code came with the reversal, but this year I've seen both (i.e. forward being both motors at 200 and assuming one will be flipped latter on and forward being one motor at 200 and one motor at 54)

3) MACROS IN ALL CAPS, varables in all lowercase. Just for ease of mine and quick reference.

Does anyone have any other ideas? Would we like this sort of thing? Gimme your input. Thanks.

-Kesich

[mightywombat]

wonderful idea. i'd suggest agreeing on a certain point in the code to declare all variables. it'd also be nice to set up a standard for commenting code. what needs to be commented and how detailed and which details... i know i wouldn't mind the extra guidance/rules, it would be good for my structure.

[echos]

as far as you convention of wheel reversal pwm01 -= 254; is probaly one of the best methods and have not had a problem with it. Thats if you set your variable type to unsigned char.

[Ian W.]

I think the best conventions to use are the ones normally used in C/C++.

Variable names are such...

thisIsAVariable = 255;

Functions are...

ThisIsAFunction ();

Tabs and spaces should be used (I think normally a tab is eight spaces, but don't quote me on that) for ease of reading. For instance...

ThisIsAFunction ()
 {
 		a = 0;
 		b = 255;
 
 		c = b - a;
 
 		return c;
 }

Something like that, which everyone should be used to be now, at least if they've taken any introductory course on C/C++ or Java.

If we want to add our own conventions, you have to set rather strict standards, and set them in the next 4 days, otherwise it'll be too late, because as soon as people start coding for the robot, they won't want to go in and change tiny things like making stuff all capitals, cause that's just annoying (even with the searc/replace features in most text editors).

Just make sure there's not too many little things to follow, otherwise it just gets annoying enough that no one will follow it. Holding down the shift key while typing half your program will get rather tedious .

[Joe Ross]

Coding conventions are a dime a dozen. do we use K&R style with opening braces on the same line as the conditional? Do we use UpperCase to seperate words in variables or underscores? 5 space tabs, 8 space tabs, no tabs? Do we prefix variables with the type?

Coding conventions in a team are very valuable. However, it will never work on a massive scale like chiefdelphi. It should be fine as long as your code doesn't look like this:http://www1.us.ioccc.org/2001/bellard.c. I do like your suggestions, though.

In fact, I would rather that the person asking the question take the extra 5 minutes to figure out what is happening then the person helping taking the extra 5 minutes to make their code look nice. But that's just me.

[Mike Betts]

ISO and ANSI standards do exist but are very costly for a school-based team (the original "standard" was LINT under UNIX).

I strongly suggest the "Indian Hill Style Guide" as a start. You can find it (and others) here: http://www.chris-lott.org/resources/cstyle/

BTW, I believe that 4 spaces to the tab (as used as default in the IDE editor) is a very acceptable standard. You will note that the IHSG does not specify the number of spaces but uses 4 spaces to the tab in their examples.

[Skabana159]

I agree- an 8-space tab is simply uncalled for. Conventions are absolutely needed within a team- especially because most teams have more than one programmer. And even if you do only have one programmer, what happens when he/she gets the flu four days before shipping and the mentor has to figure it all out? On the other hand, a FIRST-wide convention is almost impossible. Even if you examine the default code, you find sections of

ThisIsAFunction() {
}

and sections of
ThisIsDifferent()
{
}

and so on. I was going to suggest to my team that we follow the default code's conventions, but it seems to fluctuate. This is an issue that will have to be worked out by each team individually.

[Dave Flowerday]

Originally Posted by Skabana159

This is an issue that will have to be worked out by each team individually.

While it doesn't help with variable or function naming, there's a great utility out called Artistic Style. It's a free program available here. It runs under Windows or UNIX (it may need cygwin on windows, though). Anyway, it can reformat source code to follow certain specifications (such as put the braces on the same line as an "if" or on the next line, spaces around operators, indentation guidelines, whether or not to use tabs, etc). Works great for taking code written by a bunch of different people and making it follow one standard.

As a side note, most coding standards used by companies explicitly forbid the use of tabs in source code. While it is certainly up to you, I highly recommend you only use spaces to indent. It makes code so much easier to read when opened in another editor that uses a different number of spaces per tab. Any decent editor should allow you to have the tab key automatically insert the correct number of spaces instead of inserting a tab anyway, so it really shouldn't be any harder to not use tabs.

[Adam Y.]

ISO and ANSI standards do exist but are very costly for a school-based team (the original "standard" was LINT under UNIX).

Umm.. Aren't most C compilers ANSI C and ISO compliant? I didn't think that their standards related to the way you formated text.

[Mike Betts]

Originally Posted by Adam Y.

Umm.. Aren't most C compilers ANSI C and ISO compliant? I didn't think that their standards related to the way you formated text.

"The nice thing about standards is that there are so many to choose from."

[Adam Y.]

"The nice thing about standards is that there are so many to choose from."

Why it appears the only standards that anyone should concern themselves with is ANSI and ISO.

[rwaliany]

whatever gets the job done...and what ever comments make it easier to read and understand to explain what gets the job done

[Anthony Kesich]

All good suggestions, and i do understand that a FIRST-wide set of conventions simply cannot be done, but my one main problem was never addressed. Should motors be assumed to be later reversed (whether it be software or hardware), or should all motors be assumed to be unreversed?

Originally Posted by echos

as far as you convention of wheel reversal pwm01 -= 254; is probaly one of the best methods and have not had a problem with it. Thats if you set your variable type to unsigned char.

wait, i dont think that works, but correct me if I'm wrong. Take pwm01=200. 200-254=0 with 54 more to roll over. So you then get 255-53, which then gives you 202, which is definately not what you are looking for. I, myself, have decided to stick to what I used in basic which was pwm01=254-pwm01.

[intx13]

It's all about Hungarian notation. Microsoft makes all their new programmers go through courses on Hungarian before they ever touch a compiler. I don't know if it deals with stuff like number of spaces or whatever, but it lays out the naming of variables. For instance:

lets say you have an integer storing average speed. An appropriate name might be nAvSpeed. The "n" prefixes the variable type, and all important parts of the name are capitalized.

chTest: character
sTest: structure (it think)
ptrsTest: pointer to a structure
...

[Greg McCoy]

Originally Posted by intx13

Microsoft makes all their new programmers go through courses on Hungarian before they ever touch a compiler.
...

Seems like to me this is a reason not to do it

Seriously though, standardized coding conventions would help a lot, especially for teams that need programming help. Even if you just standardized within your team, it would be much better to be able to go back and forth between several years of robots and be able to use more of the same code with less editing. I think it's a good idea, but will take someone who is really devoted to developing a good standard and sticking to it for it to work for the entire FIRST community. The best thing we can do is use plenty of comments and stay consistant at least in our own programs