Chief Delphi - Programming Organization

Chief Delphi (http://www.chiefdelphi.com/forums/index.php)

- Programming (http://www.chiefdelphi.com/forums/forumdisplay.php?f=51)

- - Programming Organization (http://www.chiefdelphi.com/forums/showthread.php?t=40587)

coastertux

22-11-2005 16:00

Programming Organization

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	22-11-2005 16:20

Re: Programming Organization

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

Code:

// Good

if(foo == bar)

{

return;

}



// Bad

if(foo == bar){

return;

}

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

Code:

// 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.

Code:

// Good

void Read_Encoder(void)



// Bad

void ReadEncoder(void)

Use short, clear and concise variable/function names.

Code:

// 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.

Code:

// 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

22-11-2005 17:06

Re: Programming Organization

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	22-11-2005 17:09

Re: Programming Organization

Quote:

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 :p

Timothy D. Ginn

22-11-2005 18:01

Re: Programming Organization

Quote:

Originally Posted by coastertux

...
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. ...
Also, how can we divide the programming and then get it all back together into one easily?

Thanks!

Well, congratulations on being able to find such numbers; it seems to be rare that teams will get that many people interested in programming.

The advice given so far about using some version management system (like for example CVS or Subversion) is good (actually, it's even handy if you were the only one programming since if you're ever in a situation where you make a big oops you can revert back to a good copy).

One thing that I would like to add though, is that with such a large group I would consider it likely that there will be problems with certain members not having enough to do at times (which can spin off into a feeling of not making a valuable contribution and eventually a lack of interest in attending) none of which are good things. Be very careful about this; it's not always easy to notice and people won't always admit if they're feeling left out. Assuming your programming team does both robot and website programming it might be worth splitting into two subgroups so that people can take ownership of a particular task.

lndnny

22-11-2005 19:42

Re: Programming Organization

Quote:

Originally Posted by Mike

Code:

// Good

if(foo == bar)

{

return;

}



// Bad

if(foo == bar){

return;

}

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

Code:

// 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.

Code:

// Good

void Read_Encoder(void)



// Bad

void ReadEncoder(void)

Use short, clear and concise variable/function names.

Code:

// 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.

Code:

// Good

/* Bad */

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

-Anonymous

Code:

// Good

if(foo == bar)

{

     return;

}



// Bad

if(foo == bar){

     return;

}

you should indent stuff between brackets

Cuog	22-11-2005 19:55

Re: Programming Organization

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

22-11-2005 20:40

Re: Programming Organization

How would I set up a SVN/Subversion?

Rickertsen2

22-11-2005 23:46

Re: Programming Organization

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

TimCraig

23-11-2005 00:51

Re: Programming Organization

The primary purpose of coding standards is to make the source code easy to read. While the compiler may not care, source code MUST be readable by humans. If you're used to the standard in place, sometimes you can glance at a piece of code and know there's a problem because it just doesn't look "right". When the body of code is uniform, it's just easier to read and understand. This may not seem all that important on small projects like the control code for a FIRST robot, but for real projects of half a million lines of code, it becomes very important for productivity. On projects like that people come and go and it's important that things be clear and concise.

FWIW, the example programs that come with Microsoft's Visual Studio are NOT good examples of how to program in a production environment. In fact, most of the examples roaming around the web are pure crap. Unfortunately, this obervation probably also applies to the majority of production code in acutal software products.

Dave Scheck

23-11-2005 10:51

Re: Programming Organization

Quote:

Originally Posted by Mike

Use double slash comments.

Code:

// 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	23-11-2005 13:35

Re: Programming Organization

Quote:

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.

23-11-2005 15:53

Re: Programming Organization

Quote:

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.

WizardOfAz

23-11-2005 17:01

Re: Programming Organization

I would second the recommendation by Mike Sorrenti ealier in this thread about using CVS to share code among the programmers and manage changes. An environment that integrates CVS very nicely is Eclipse. See this thread (http://www.chiefdelphi.com/forums/sh...ad.php?t=37736) for information about using Eclipse for FRC development. We've switched to it, and will never go back. You basically trade Eclipse for MPLAB, and although you lose the simulation capability, it is not all that useful for FRC projects anyway. In exchange, you get CVS, a C-aware editor, and experience with an IDE environment that is the standard in many commercial development shops.

It will take some learning and effort to get the eclipse and CVS environment set up, and for you to understand how to steer it, so if you're going to do it, start now so you're up to speed before competition season. Pretty good information is available in the CD thread mentioned above, and a few others you can find by searching for Eclipse. I am willing to help via PM or even phone, as long as the level doesn't get overwhelming.

BTW - Eclipse is open source and free, so there are no costs or difficult licensing issues.

If you want CVS but not Eclipse, maybe TortoiseCVS would be the way to go. It's also free and open-source.

You can get a free CVS account from sourceforge.net. By using it, you are not only getting change control, sharing among your team members, and backup, but you're sharing with other FIRST teams - in true FIRST spirit!

You can see all of our code there, in sourceforge project "crush1011".

Bill Bennett

Dave Scheck

23-11-2005 17:01

Re: Programming Organization

Quote:

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.

Quote:

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 ;)

DonRotolo

23-11-2005 17:30

Re: Programming Organization

Quote:

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

TimCraig

24-11-2005 01:51

Re: Programming Organization

Quote:

Originally Posted by Dave Scheck

Please not that C compilers are not required to support the double slash style comment.

For a C compiler to be compliant with the ISO/ANSI C99 standard, it must accept the // style comments. These were not in the earlier C89 standard although most mainsteam compilers accepted them as an extension. The problem is the demand for pure C has dropped in favor of C++ and the bulk of users are probably now in the embedded market. So many of the compilers there haven't been updated to be compliant with the new standard, probably to lower sales volumes. Although recognizing the // style comment should be child's play to a compiler writer whom you're going to entrust with optimizing your source into machine code.

Astronouth7303

24-11-2005 22:18

Re: Programming Organization

Everything said so far is good. Here is my list of the important stuff:

Use a standard formatting style. This includes how to position braces ({ and }), spacing between arguments, amount of indent (2 spaces, 4 spaces, or a tab), line overflow, etc. I believe the de facto standard of C is like this:

Code:

// You should use more descriptive names for everything

void AFunctionName(int an_argument, int other_argument)

{

        int retval = DoSomething(other_argument, an_argument + 1);

        int n = 0;

        for (int i = 0; i < retval; i++)

        {

                // So, do something here...

                n = an_argument * i;

        }

}

Use a versioning system. CVS and Subversion are the best (only) free ones I've heard of. Do some googling as to how to use them/set them up. If used appropriately, this can also cover changelogs. (Write a descriptive commit message! I prefer many commits with specific changes to few large commits that can't have a good description.)

Document. I find doxygen works well for API-type documentation (Which functions do what, and what arguments they take). For logic documentation, nothing beats good ol' comments.

Create functions for conceptual reasons. A function should perform a specific task, and that task should be fairly clear from the name. (And having clearly named functions with unambiguous purposes also helps with self-documenting code, if you believe in such a thing.)

I agree entirely with teaching basic OOP concepts, since that includes ideas of abstraction and encapsulation (not to mention a few other things), concepts I consider important to writing clear code that works.

Code reuse. Last year, I used a system much like the autonomous scripting to handle motor control (control loops). This was a great boon for me, because when part of the robot didn't work, I could say, "It's not the code. The same code works on the other joint." (This is greatly undervalued. Definately going to do something similar again.)

Many files are good. You should actually reduce the number of functions in user_routines.c and user_routines_fast.c. Have a file devouted to translating human input, another one for driving, and several for autonomous. (I consider autonomous a 95-10 situation: 95% of your work goes into 10% of the match.)

In 2004 (code) and in 2005, I organized code based on function on the robot. All the hardware interaction went through abstraction macros/functions. This ment higher-level code would do things like:

Code:

 //user_routines.c, line 175

 //Map Joysticks to drive train

 Drive_Joystick(OI_Left, OI_Right);

While code farther in would be doing:

Code:

// Drive.c, line 51

void Drive_Joystick(char Left, char Right)

{

        if(Left > 127)

        {

                Left_CIM = Left_Drill =  (128 + JOYSTICK_SMOOTHING[Left - 127]);

        }

        else

        {

                Left_CIM = Left_Drill = (127 - JOYSTICK_SMOOTHING[127 - Left]);

    }

    

//        Right_CIM = Right_Drill = Right;

           if(Right > 127)

        {

                Right_CIM = Right_Drill =  (128 + JOYSTICK_SMOOTHING[Right - 127]);

        }

        else

        {

                Right_CIM = Right_Drill = (127 - JOYSTICK_SMOOTHING[127 - Right]);

    }

}

(These same routines were used for autonomous, as well.)
This is a simplistic sample. The Hand_*() functions in Grabber.c (which maybe should have been broken up) are the most complex, due to the current-limiting sensor. BTW, this example is not from the year I used doxygen, so the functions themselves are poorly documented. *_Check() functions compared the input value to the current value and reacted appropriately (except the drive code, which just mapped input to output without feedback).

prograid

25-11-2005 21:39

Re: Programming Organization

If you are intent upon using Subversion (like someone I know is.) and you want to use Eclipse (which I do) then I would suggest using an Eclipse plug-in called Subclipse. It's made by the same people that make Subversion. It's not as nice as Eclipse's CVS integration but it's more than adequate for FIRST purposes. Also, more information on Eclipse (e.g. installation instructions, setting up a basic project, etc) along with an updated version of my plug-in can be found in this white paper.
The white paper itself is not very useful if you are already familiar with Eclipse, but otherwise it should be helpful.

Timothy D. Ginn

29-11-2005 19:29

Re: Programming Organization

Quote:

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

29-11-2005 19:35

Re: Programming Organization

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

All times are GMT -5. The time now is 08:17.