Programming Organization

[coastertux]

Last year we only had 2 students programming so we both worked on the same piece of code and didn't worry too much about conventions, etc. This year it looks like we will have about 8 people on the programming team and were wondering how we can manage that many people. What types of conventions like indents, variable names, function names, constants, and comments can we require? Also, how can we divide the programming and then get it all back together into one easily?

Thanks!

[Mike]

First off, I'd recommend setting up a CVS (Concurrent Versions System) server. Concurrent Version System - Wikipedia, the free encyclopedia

As head programmer (which I'm assuming you are), I would setup a set of standard header files. These would be included in the necessary source files, with each header file being completely independent and modular. Say you need to use PID control in a source file, you should just have to include pid.h and it should cover everything you need.

To be honest, I wouldn't worry too much about indent size/function names/etc. Have enough of a standard to make it readable, but not enough to hinder a persons programming time because they have to look up whether it's Function_Name or function_name.

With that being said, I admit to being a perfectionist. This is my current self-standard:
All brackets are placed on next line

// Good
if(foo == bar)
{
return;
}

// Bad
if(foo == bar){
return;
}

Constants are referred to in capitals, all others in lower case.

// Good
#define PI 3.14
unsigned int some_variable;

// Bad
#define pi 3.14
unsigned int SOME_vArIABLE;

Variables/Functions use underscores to replace spaces.

// Good
void Read_Encoder(void)

// Bad
void ReadEncoder(void)

Use short, clear and concise variable/function names.

// Good
unsigned int left_encoder_clicks = 0;
void Update_Encoder_Count(void)

// Bad
unsigned int amount_of_clicks_back_from_the_encoder = 0;
void Update(void)

Use double slash comments.

// Good
/* Bad */

Like I said, try to not have super-harsh standards. These are my own, and I realize that they probably are pretty strict... but they are for myself only. If I were to work with a programming team, they would be much more lax.

EDIT: I'd just like to add that I change my standards a lot... just because I'm a perfectionist like that.

The great thing about standards is there are so many to choose from.

-Anonymous

[Rickertsen2]

Plan plan plan plan plan and plan your code before writing it. Agree on interfaces between code bits ahead of time. C is a loose and rather permissive language so it is important to agree on coding standards. A CVS is a good idea. Document the code well. Maintain change logs. Document everything where reasonable. Abstract and encapsulate where reasonable. Modular code helps with group projects. It is one thing to be able to write code that you understand. It is another to write code that can be easily modified and understood by others.

I have a guide NOT to follow: How to write unmaintainable code

[Mike]

Originally Posted by Rickertsen2

I have a guide NOT to follow: How to write unmaintainable code

On a somewhat-kinda-related tangent, visit TheDailyWTF and make sure not to do anything you see there

[DonRotolo]

Originally Posted by Rickertsen2

Document the code well. Maintain change logs.

Both are excellent ideas, and will save you a ton of grief when things don't work right.

I personally document every line of code, and usually my code has more comments than code. Comments should be sufficient for anyone moderately familiar with code to understand completetly and fully what a line is supposed to be doing.

Cange logs are harder to enforce, but literally writing down every change (was Foo == bar, changed to foo==bar, DAR 11/23/05) with who did it and when can be extraordinarily useful when something that was working suddenly stops. Reviewing it later is also an excellent learning tool, you see how things evolved and learn ways to get there sooner next time. (Note that some CV systems do this for you)

This is how professional programmers are supposed to do it. Sadly, it's not always the case, but projects that do are often more successful. Learn it the right way, the discipline will serve you well for a lifetime.

Don

[lndnny]

Originally Posted by Mike

First off, I'd recommend setting up a CVS (Concurrent Versions System) server. Concurrent Version System - Wikipedia, the free encyclopedia

As head programmer (which I'm assuming you are), I would setup a set of standard header files. These would be included in the necessary source files, with each header file being completely independent and modular. Say you need to use PID control in a source file, you should just have to include pid.h and it should cover everything you need.

To be honest, I wouldn't worry too much about indent size/function names/etc. Have enough of a standard to make it readable, but not enough to hinder a persons programming time because they have to look up whether it's Function_Name or function_name.

With that being said, I admit to being a perfectionist. This is my current self-standard:
All brackets are placed on next line

// Good
if(foo == bar)
{
return;
}

// Bad
if(foo == bar){
return;
}

Constants are referred to in capitals, all others in lower case.

// Good
#define PI 3.14
unsigned int some_variable;

// Bad
#define pi 3.14
unsigned int SOME_vArIABLE;

Variables/Functions use underscores to replace spaces.

// Good
void Read_Encoder(void)

// Bad
void ReadEncoder(void)

Use short, clear and concise variable/function names.

// Good
unsigned int left_encoder_clicks = 0;
void Update_Encoder_Count(void)

// Bad
unsigned int amount_of_clicks_back_from_the_encoder = 0;
void Update(void)

Use double slash comments.

// Good
/* Bad */

Like I said, try to not have super-harsh standards. These are my own, and I realize that they probably are pretty strict... but they are for myself only. If I were to work with a programming team, they would be much more lax.

EDIT: I'd just like to add that I change my standards a lot... just because I'm a perfectionist like that.

The great thing about standards is there are so many to choose from.

-Anonymous

// Good
if(foo == bar)
{
     return;
}

// Bad
if(foo == bar){
     return;
}

you should indent stuff between brackets

[Cuog]

It will also depend on what people are anal retentive about, I for example dont really care what your variable names are as long as i can easiy figure out what they mean:

useless_person //good
p //bad

But I cannot stand bad spacing/indenting, When i did team projects in my programming class last year i would go through and fix all the spacing before starting

Also everyone in your team willing to program you should teach them OOP(at least the basics) so that they are not lost in all these crazy files and their interaction.

Our team also has a small programming base and we like it that way:
2 people now three that i Switched from JAVA and C# to PIC "C"

[coastertux]

How would I set up a SVN/Subversion?

[Rickertsen2]

8 people is quite alot for such a small project. What is the experience level of each member like?

[Timothy D. Ginn]

Originally Posted by coastertux

How would I set up a SVN/Subversion?

A brief description of many free version control system is at http://producingoss.com/html-chunk/vc-systems.html (I just happened to stumble across that by chance when reading something else and figured you or others might be interested).

For how to setup a repository see http://subversion.tigris.org/faq.html#repository (how to make Eclipse use it has already been mentioned).

[coastertux]

We are using CVS now as I could not find a free SVN server.

[Dave Scheck]

Originally Posted by Mike

Use double slash comments.

// Good
/* Bad */

Please not that C compilers are not required to support the double slash style comment. I would try to stay with the language specific comments for portability. If IFI were to change the RC and we needed a new compiler, there would be a chance that it wouldn't support the double slashes. In that case, you would be causing yourself to do extra work in porting the comments.

We actually just ran into this exact issue when teaching our software students. We designed labs and homework using the mcc18 compiler and mistakenly had double slash comments in some places. When we gave them the assignments, they were to use a gcc compiler. We found out quickly that gcc doesn't support the double slash and we had to go back and fix it.

[Mike]

Originally Posted by Dave Scheck

We found out quickly that gcc doesn't support the double slash and we had to go back and fix it.

Hmm, that's weird... I use avr-gcc (a gcc port for the AVR line of microcontrollers) and it allows the double-slash style.

But like I said, that is my personal standard.

[Ryan M.]

Originally Posted by Dave Scheck

We found out quickly that gcc doesn't support the double slash and we had to go back and fix it.

Really? Hm... works fine here.

And as a side note, while I agree with Dave, '//' is supported by the MCC18 compiler.

[Dave Scheck]

Originally Posted by Mike

Hmm, that's weird... I use avr-gcc (a gcc port for the AVR line of microcontrollers) and it allows the double-slash style.

Originally Posted by Ryan M.

Really? Hm... works fine here.

The gcc that failed was version 3.4.2 for ming. I tried it with gcc 3.4.4 for Cygwin and it works fine.

I guess this proves my point that it's best to use the /**/ style for portability