Chief Delphi

Chief Delphi (http://www.chiefdelphi.com/forums/index.php)
-   Programming (http://www.chiefdelphi.com/forums/forumdisplay.php?f=51)
-   -   Coding / Style Standards for sharing C code (http://www.chiefdelphi.com/forums/showthread.php?t=28285)

Joe Johnson 29-04-2004 08:26

Coding / Style Standards for sharing C code
 
There is a thread here: http://www.chiefdelphi.com/forums/sh...589#post259589

were a bunch of folks are thinking that it would a good idea to have a place to share code for running FIRST robots.

I started to put this idea on the end of that thread, but I decided it needed its own thread, so here it is.


Before we go too much farther on the idea of an open source movement for FIRST code and/or a code repository, I think it would be wise to putting some thought into a choice of a coding standard/coding style.

By this I mean many things.

Starting with the trivial, like using X spaces as an indent (and NOT tab chacters) and where to put the { after an if statement. But there is more than that to work through.

It would be nice to see some agreement on naming conventions (e.g. constants are all caps with underscores between words THIS_IS_A_CONSTANT, variables begin with a noncap and use caps between words thisIsAVariable -- this are just examples, I am not actually proposing this as a standard).

Beyond this there are some even higher level things that we can agree on that will save us a lot of hassle when we try to integrate code from many source (e.g. we may decide not to allow using nested macro definitions or we may try to encourage use of enum to define constants rather than macros or maybe we can agree on a something as simple as where to put [] in macro definitions to keep from generating subtle math errors). Another idea is we may all want to use the same lint-type program before publishing the code.

Anyway, my point is there is a lot of ways we can make this library easier to understand, use and improve if we can get some agreement on a set of standards and/or a coding style before we get too many things into the library.

I am not the right person to lead this but I know there are a lot of good coders out there with a lot of good experience with this type of thing. Is there someone or some small group of someones willing to take this on?

It would be a great service to the FIRST coding community.

Think about it.

Joe J.

MikeDubreuil 29-04-2004 08:39

Re: Coding / Style Standards for sharing C code
 
maximum number of columns per line?

This website recomends no more than 79 columns or some terminals may have problems.

Joshua May 29-04-2004 09:18

Re: Coding / Style Standards for sharing C code
 
I think it might be good for some sort of a uniform header for each function, that explains type, purpose, arguments, and usage.

Joe Ross 29-04-2004 09:31

Re: Coding / Style Standards for sharing C code
 
Dr. Joe, Here is a discussion from the beginning of the year on this: http://www.chiefdelphi.com/forums/sh...ad.php?t=23345

MikeDubreuil 29-04-2004 09:43

Re: Coding / Style Standards for sharing C code
 
Another thing to be decided on...

I've notices some people are using -127 to +127 values in example source code. And then they hope that people will convert them to the necessary 0 to 254 values. Should a function in the library be allowed to return a non-converted value? Or should it be noted that the function returns values on the scale from -127 to +127, and the end user must use another function (avaliable in the library) to convert that value to a usable one?

Guest 29-04-2004 09:58

Re: Coding / Style Standards for sharing C code
 
I don't think C has enums (unfortunately).

Mark McLeod 29-04-2004 10:46

Re: Coding / Style Standards for sharing C code
 
Here are some considerations for coding standards/styles from off the top of my head. I have opinions on all of these, but tried to eliminate them as I typed (I did let a few sneak by).

See if there are issues you can add to these. I'll edit this later to add definitions.


1) Use ANSI C standard

2) Design Considerations


a. Information hiding
b. Context based control
c. Object oriented programming
d. Modular solutions
e. Memory allocation

3) Error Handling


a. External status
b. Debugging tracebacks
c. Programmer debugging

4) Encapsulate or isolate CPU specific code dependence, e.g., PIC specific calls like timers, ADC. (we will upgrade to a new processor one day and it will be nice to easily take the existing repository code with us)

5) Avoid duplication of purpose



6) Miscellaneous
a. Use of defines, enum, etc. rather than embedded constants
b. No default Boolean tests
c. No syntax changes via macros
d. No nested macros
e. Avoid function like macros that do not behave like functions
f. No more than 80 characters per line
g. Standardize indents (I also much prefer spaces to TABs)

7) Naming conventions
a. Functions
b. Macros
c. Typedefs
d. Defines
e. Includes
f. Project Files

8) Documentation
a. Project file headers w/version, date, update history
b. Function headers
c. Non-function headers
d. Additional information blocks
e. In-line documentation
f. Manual pages


We’ll have to decide how to assign proper credit. We shouldn’t take up a lot of real estate with Team credits, but a single standard line would be nice. My guys like to put banners on that take up the whole screen. I hate that because it’s so much junk to skip over every time I need to look at a file.

MikeDubreuil 29-04-2004 11:17

Re: Coding / Style Standards for sharing C code
 
Under what license should we publish our software?

Joe Johnson 29-04-2004 11:32

Re: Coding / Style Standards for sharing C code
 
Quote:

Originally Posted by MikeDubreuil
Under what license should we publish our software?

My strong preference would be for the license to be be free ("as in free beer" - for those open source folks reading this), but I realize that many people have stong feelings about this plus I realize that many useful software will likely be developed based on other open source stuff with their own license limitations...

...so, I suppose we will have to have several license levels based on some combination of the author's wishes and the license that the software was developed from (some maybe license free, some maybe gpl, some with other licenses).

BOTTOM LINE: I don't really want to hash all these details out here in public on the CD forum without some strong leadership. I am BEGGING for someone (or group of someones) who really have their arms around all these issues to do some serious noodling on this topic and then come back with a workable solution (perhaps with open comment periods, etc.).

Will some of you bit heads grab the reins on this one? Please?

Joe J.

Mark McLeod 29-04-2004 12:28

Re: Coding / Style Standards for sharing C code
 
I also am a "free software" proponent. I like a community produced final product.

I don't mind producing a draft coding standard for community review.
In my experience however, only a dedicated few will actually spend the time to read through such a thing. Unless maybe it fits on a single page. At work coding standards get enforced because they have teeth and are verified through peer or QA code reviews. Only after a while does it become habit or second-nature. I don't believe that's a model that will take root in FIRST, although, it would give students a nice exposure to "standard" business practices. It's more a Team enforceable thing because the Teams changeover so much every year. I don't know who would reject a really sweet piece of code because it didn't comply with the coding standard.

-The easiest document to agree on will probably be generic coding conventions.

-A second standard could address FIRST robotic specific standards. For example, one of the most common issues this past season was the pwm definition dichotomy of (0 to 254) or (-127 to 127). My Teams switched to standard math (-127 to 127), but whenever I helped students with questions on CD I'd have to convert the code back (0 to 254) and I introduced silly mistakes sometimes.

However, both these "standards" are defined and demonstrated by the default code released by Innovation FIRST. The IFI default code will always define the de facto coding standard.
The active CD community is somewhat smaller since the season has ended, so if we decide to do something like this we will have to contact the most active experienced programmers directly for their input.

MikeDubreuil 29-04-2004 12:42

Re: Coding / Style Standards for sharing C code
 
Quote:

Originally Posted by Mark McLeod
I don't mind producing a draft coding standard for community review.
In my experience however, only a dedicated few will actually spend the time to read through such a thing...
The active CD community is somewhat smaller since the season has ended, so if we decide to do sometime like this we will have to contact the most active experienced programmers directly for their input.

I think it would be great if some of the FIRST software engineers put together a software standard (yourself, Ken Wittlief, Kevin Watson, and company).
I know I would follow it when I contribute to the library and use it at the stadard when teaching the students I mentor.

EDIT:
Quote:

A second standard could address FIRST robotic specific standards. For example, one of the most common issues this past season was the pwm definition dichotomy of (0 to 254) or (-127 to 127).
My opinion would be the best way to handle this is to let the coder use whatever system he wishes. Just make sure it is clearly documented in the code which type the function will output. Then we could create two standard functions that convert between the two definitions. We should also create official names for the two different definitions.

Joe Johnson 29-04-2004 13:33

Re: Coding / Style Standards for sharing C code
 
Okay, Mark is one. How about some more folks? Dave Flowerday? Kevin Watson? How about someone from IFI -- that would be nice? Mike Betts, are you listening? Jason Morella & Dave Lavery, you were advocating a pretty strongly for some code sharing, perhaps you folks are not the right people, but you can find a body fill the seat and start rowing can't you?

I am hoping for a group of 5 or so folks to make this happen.

I am thinking that Brandon can make you folks a special (private or moderated -- your choice) forum to allow you to get some things hashed out quickly. Perhaps I will host some conference calls at the start and as needed after that, but others are going to have to carry the ball down the field.

Volunteer now!

Joe J.

Max Lobovsky 29-04-2004 14:06

Re: Coding / Style Standards for sharing C code
 
Wait a second, shouldn't we decide the goal of this thing (i dont even know what to call it yet) before we get into as specific a detail as the length of a line? Aren't we getting way ahead of ourselves. Here are some questions i think we should answer first:

What types of software will be included? (RC code only or any FIRST related code)

What form will each "element" of this repository take? (complete compileable programs, entire files to replace/add to the default code, or just small snippets (like what's at http://nrg.chaosnet.org/repository/)

What people/organization should manage this? (like what Joe Johnson was talking about)

Greg Ross 29-04-2004 14:59

Re: Coding / Style Standards for sharing C code
 
Quote:

Originally Posted by SilverStar
I don't think C has enums (unfortunately).

Indeed it does.

Dave Flowerday 29-04-2004 15:09

Re: Coding / Style Standards for sharing C code
 
Quote:

Originally Posted by Joe Johnson
Okay, Mark is one. How about some more folks? Dave Flowerday? Kevin Watson?

I'm willing to help out too, although I agree with Mark that it will be difficult to convince teams to follow a coding standard which isn't one that they created. I know here at work our coding standard gives a reasoning for each stipulation like where the braces go and such, and for most of them the reason is just basically "We had to pick one, and this is the one we picked. Deal with it." Instead of asking teams to follow a coding standard, maybe just enforce the standard on code in the repository? Teams wouldn't have to follow the standard (unless they wanted to add code to the repository), yet anything they pull from the repository would still follow a consistent standard. Perhaps, just like most software companies, code should be reviewed by a group of peers before it's accepted into the repository? That would make it easy to at ensure that the code in the repository followed some standard and also give users of the code some level of confidence that the code is decent and relatively bug-free. It would potentially discourage some contributors, but maybe that's better than having a repository that is just flooded with code, some useful, some incomprehensible, some that works, and some that doesn't?

Also, I've mentioned it before I think, but there's a wonderful little tool available for Unix/Linux and Cygwin that could be useful here - it's called "Artistic Style" and it will reformat code to a certain standard - it lets you specify tabs versus spaces, indent levels, whether to attach braces or put them on the next line, etc. I use it at work quite a bit to easily bring outside code at least that much closer to the rest of ours.


All times are GMT -5. The time now is 16:29.

Powered by vBulletin® Version 3.6.4
Copyright ©2000 - 2017, Jelsoft Enterprises Ltd.
Copyright © Chief Delphi