Coding / Style Standards for sharing C code

[Joe Johnson]

There is a thread here: http://www.chiefdelphi.com/forums/showthread.php?p=259589#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]

maximum number of columns per line?

This website (http://www.doc.ic.ac.uk/lab/secondyear/cstyle/node2.html#SECTION00020000000000000000) recomends no more than 79 columns or some terminals may have problems.

[Joshua May]

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]

Dr. Joe, Here is a discussion from the beginning of the year on this: http://www.chiefdelphi.com/forums/showthread.php?t=23345

[MikeDubreuil]

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]

I don't think C has enums (unfortunately).

[Mark McLeod]

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) Miscellaneousa. 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 conventionsa. Functions
b. Macros
c. Typedefs
d. Defines
e. Includes
f. Project Files

8) Documentationa. 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]

Under what license (http://www.gnu.org/philosophy/license-list.html) should we publish our software?

[Joe Johnson]

Under what license (http://www.gnu.org/philosophy/license-list.html) 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]

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]

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

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]

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]

I don't think C has enums (unfortunately).
Indeed it does.

[Dave Flowerday]

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.

[Gene F]

I too would be willing to contribute to this effort. I like the idea of using a program to "beautify" the code before submitting it. I also believe that we should have some kind of rating system so that it is easier to identify the value of contributions to the community. It would make it easier to maintain the repository over the long haul. Anyone that downloads the code would be asked to rate it on several metrics like quality of code, clarity of documentation, value of functionality, etc.

I too, like Dave, do this kind of thing for a living.

[Kevin Watson]

Okay, Mark is one. How about some more folks? Dave Flowerday? Kevin Watson?You guys might want to start with something like the Indian Hill C Style and Coding Standards (http://www.chris-lott.org/resources/cstyle/indhill-cstyle.html) document.

-Kevin

[Ian W.]

If you give the teams a reason to use the "CD Standard" then they will use it.

For instance, we create a code depository with every single line of code following the "CD Standard." We also get IFI, or someone who can work closely with IFI to set the default code up in the "CD Standard." Furthermore, make sure that teams can "drag and drop" code from the depository into the default code with little to no effort at all, so that teams can quickly get a working program.

When you set things up, and, well, force the teams to use the "CD Standard," most teams will follow suite and use it. Also, perhaps make a rule that any true C code (not pseudo-code, for obvious reasons) must be in the "CD Standard" for us to quickly give help and answers. Another forum I frequent (Gentoo Linux Forums, http://forums.gentoo.org), the forum members usually ask for posters to remove comments from their configuration files so they don't waste everyones' time by making them re-read all the comments in XF86Config again. It's a simple request, and yes, it's not the nicest thing to do, but it enforces the standard, which in the end, should make it easier for everyone.

The thing about a standard is, everyone has to use it, or else it's not really a standard, and you've just basically wasted your time, and we all know that from January to late February, we don't have any time to waste ;).

[Mark McLeod]

You guys might want to start with something like the Indian Hill C Style and Coding Standards (http://www.chris-lott.org/resources/cstyle/indhill-cstyle.html) document.

-KevinI agree Kevin. That's what I've used before.
I also agree with employing a "Pretty Print" style clean-up program as Dave suggested to make it easier to be sure new code adheres to the CD standard.
And Gene's rating system is interesting.

I think the coding standard itself will be fairly easy to define.
For general consumption I think we'll need to be able to condense the major points to one or two sheets of bullets that is then backed by the in-depth standard definition and reasoning.

[edit] We'll need to think hardest about platform (PIC) specific and IFI specific standards.

[Greg Ross]

I am thinking that Brandon can make you folks a special (private or moderated -- your choice) forum

Brandon, don't you love it when people volunteer you for more work? :D (And I think maybe a moderated forum and an associated white paper section would be good.)

Anyway, I am interested in being a part of this project too.

I agree with Dave's suggestion that code should be peer reviewed before it is accepted into the repository.

I also agree with Kevin's suggestion that we start with an established standard, rather than reinventing the proverbial omni wheel.

Max, you've got some good questions, but I don't know that every one needs to be tacked down before we consider coding styles. Maybe another thread for that?

[mtrawls]

For general consumption I think we'll need to be able to condense the major points to one or two sheets of bullets that is then backed by the in-depth standard definition and reasoning.

Maybe this article (http://www.perl.com/pub/a/2000/01/CodingStandards.html) will help? (Ignore perl specific stuff, obviously.) Specifically:


Coding standards needn't be onerous. Just because there are bad coding standards out there, doesn't mean that all coding standards are bad.

I think the way to a good coding standard is to be as minimalist as possible. Anything more than a couple of pages long, or which deviates too far from common practice, will frustrate developers and won't be followed. And standards that are too detailed may obscure the fact that the code has deeper problems.


This sounds like a really good idea, and I hope it proves successful.

[Greg Ross]

For general consumption I think we'll need to be able to condense the major points to one or two sheets of bullets that is then backed by the in-depth standard definition and reasoning.
Maybe this could be in the same form as the FAQs here on CD, where there would be single line statements of each point of the standard, and those would be linked to the in-depth definitions.

[Mark McLeod]

We probably should address repository, software licenses, the rating system, and other side-issues in either the original thread or in new threads and keep this one focused purely on coding standards. Since the original thread was co-opted we might want to start a new thread with a title like "Code Repository."

Okay, let's think about this.

Indian Hill C Style Guide as a basis
Bring up and discuss any dissentions or alternative styles
Associated assembly code standards
Additions/extentions to the above:

-Utilities like "Artistic Style" and lint.

-Design standards (now some of these might be overkill for FIRST) like:

Information Hiding - e.g., keep variable definitions visible only to the lowest level that requires it. Within a single routine, within a Project file, or available as a Project wide global variable.

Context-based Control - e.g., functions capable of being executed independent of any previous or subsequent executions. Use context structures to maintain information that must be remembered from loop to loop.
Object Oriented approach - not true inheritance or anything like that, but for example if you have a widely used data structure you might want to develop a defined set of methods to manipulate data within the structure.
Modular functions loosely coupled to the "outside" world.

Error Handling - do we want some standardization here since people will be using the repository functions as drop-ins?
Function interface standards
What else should we be collectively looking at?



If we can get through some initial brainstorming we can start to divide and conquer the problem.

[Joe Johnson]

Okay, here is what I think I hear so far:

Marc McLeod is in.
gwross is in.
Dave Flowerday is in.
Kevin Watson has not declared himself as "IN" but is at least making suggestions.
Many others are also interested at least in terms of comments and suggestions.

I am still waiting to hear from the Jason Morella/Dave Lavery collective to see if they have a rep they want on.

I am going to see if I can get on of the C guys from my team to "volunteer"

I also need to get in contact with Innovation First -- Perhaps we can get Bob and Tony to volunteer Mark Lambert or one of there other coders to the project.

There have been a lot of discussion/suggestions on this thread, but as I have said many times, I don't really want to solve the problem here. I think the purpose of this thread should be to firm up the group of people that are going to take ownership of this thing and propose a big picture solution.

Joe J.

[Mark McLeod]

It's hard to restrain myself from start to throwing ideas around as I think of them. I'll restrain myself. I'm camping this weekend anyway, so I'll be out-of-touch until Monday.

[Joe Ross]

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

Completely license free shouldn't be an option for this project. When you release something with no license, it is covered by normal copyright laws, which are much too restrictive. Thus, the same things you learned about plagiarism still apply and effectively, you can't use the code.

Now, this may not be a problem in FIRST, as I would assume that no one would ever pursue any type of copyright violations. However, if we are going to take the time to teach students about coding standards, we should spend a few extra minutes and talk about correct licensing.

If you really want something with no license, you must explicitly grant it into the public domain. However, the person would have to agree to this when the code is entered into the repository, and a notice that this code is in the public domain would have to appear on the site.

Of course, there are many other licenses that are open source, some would be good for this project, and others wouldn't.

The BSD license (http://www.opensource.org/licenses/bsd-license.php) Allows any modification to the code to be used for any reason, as long as the license notice is retained. Thus, it is close to being public domain, but you guarantee that your name will stay with the code for posterity (as opposed to the public domain, where you could remove any notices from the code).

Another problem depends on whether the code is distributed as a library, or a snippet of code (such as a function). If you paste a snippet of code into your file (including the license), you've then licensed the whole source file. So, you are restricted from choosing your own license for other parts of your code.

If the code is distributed as a library, it is a little different. If the code licensed under the GPL (http://www.opensource.org/licenses/gpl-license.php), then anything that uses the code must also be GPL. However, if the library is licensed under the LGPL (http://www.opensource.org/licenses/lgpl-license.php), anything that uses it can have a different license.

Even if someone licenses their library as GPL, for FIRST robots, it probably doesn't mean that you have to give other people your entire robot code, however. Under the GPL, you only have to distribute your source to the people who you distribute binaries (it doesn't need to be publicly accessible). Since it isn't likely that you will be giving someone your robot's HEX file, you really don't need to distribute the source.

This last issue makes this not as big of an issue, but it should be addressed in some way.would have to appear on the site.

Of course, there are many other licenses that are open source, some would be good for this project, and others wouldn't.

The BSD license (http://www.opensource.org/licenses/bsd-license.php) Allows any modification to the code to be used for any reason, as long as the license notice is retained. Thus, it is close to being public domain, but you guarantee that your name will stay with the code for posterity (as opposed to the public domain, where you could remove any notices from the code).

Another problem depends on whether the code is distributed as a library, or a snippet of code (such as a function). If you paste a snippet of code into your file (including the license), you've then licensed the whole source file. So, you are restricted from chosing your own license for other parts of your code.

If the code is distributed as a library, it is a little different. If the code licensend under the GPL (http://www.opensource.org/licenses/gpl-license.php), then anything that uses the code must also be GPL. However, if the library is licensed under the LGPL (http://www.opensource.org/licenses/lgpl-license.php), anything that uses it can have a different license.

Even if someone licenses their library as GPL, for FIRST robots, it probably doesn't mean that you have to give other people your entire robot code, however. Under the GPL, you only have to distribute your source to the people who you distribute binaries (it doesn't need to be publicly accessible). Since it isn't likely that you will be giving someone your robot's HEX file, you really don't need to distribute the source.

This last issue makes this not as big of an issue, but it should be addressed in some way.

[Phil_Lutz]

Make it public domain and I like the idea of a library for distribution.
Building a Black-box.
The code is locked from tickering hands, and a document containing
1. function prototype
2. Description of the function
3. Original Author

Can be made up fairly easily.
Versioning of the library would simplify things too.

my 2 cents..

Phil

[Kevin Watson]

Okay, here is what I think I hear so far:
Kevin Watson has not declared himself as "IN" but is at least making suggestions.Uh oh, peer pressure :). Yes, you can pencil me in.

-Kevin

[Gene F]

Okay, here is what I think I hear so far:

Marc McLeod is in.
gwross is in.
Dave Flowerday is in.
Kevin Watson has not declared himself as "IN" but is at least making suggestions.
Many others are also interested at least in terms of comments and suggestions.

I am still waiting to hear from the Jason Morella/Dave Lavery collective to see if they have a rep they want on.

I am going to see if I can get on of the C guys from my team to "volunteer"

I also need to get in contact with Innovation First -- Perhaps we can get Bob and Tony to volunteer Mark Lambert or one of there other coders to the project.

There have been a lot of discussion/suggestions on this thread, but as I have said many times, I don't really want to solve the problem here. I think the purpose of this thread should be to firm up the group of people that are going to take ownership of this thing and propose a big picture solution.

Joe J.

Please count me in too.

[Astronouth7303]

Here's my 2 cents. (Wrote this up yesterday)
My thoughts on what the standard should be:

Allow C++ style comments
1 of the properties of each upload should be "Target System". Right now there only is 5: 'PBASIC Stamp (EDU)', 'PBASIC Stamp (Full)', 'PIC18Fxx (EDU)', 'PIC18Fxx (Full)', and 'None'. 2 of the same processor can be selected (not EDU/Full specific)
Hardware info should be noted and ALIASed. (is that a word?) This allows for rapid integration.
Actual formating should be uniform with the default code (except for the C++ comment thing)
any TABS included will be changed to 4 spaces on upload (or just rejected outright)
only debuged code should be uploaded.
upload as file(s), NOT textbox.
allow multiple files in upload
a set of standard libs, functions, etc. are provided ('#include <Repositroy.h>') (Or assumed to be provided)
items-in-progress should be marked as such
currently, only .h, .c, .bsx, and .zip files are allowed for actual code (Probably will expand)
Zips can contain full projects, but files MAY be filtered out as deemed necessary by the moderator(s)
tools, etc. are kept seperate from code. all tools must be open source. (A 'tool' is anything related to code but is not actually code itself)
all code has same EULA: 1) Code is given AS IS. 2) give credit where credit is due. 3) may NOT use code to make money.
White space should be included where the C spec allows.
PLENTY OF COMMENTS
a whitepaper/explainitory file can be included (seperate from code, but accesed together)
I know there's more...

I'm focusing more on the repository than the code itself.

Some stuff from the first thread:

Integration into CD. [...]
More nesting of categories. I know that isn't an issue (yet), but if this thing takes off...
[...]
Improved interface (I'm too used to CD!)


I am willing to help hammer this thing out/code it/whatever. Be warned: I'm 15 (almost 16) and don't have any professional coding expierience. I encourage the guys who end up making this (Why just the profesionals?) to get a forum, but I think keep it public. Those who aren't actually writting should try to restrain from posting there, but I think they should be able to.

What's the noun for "a piece of code that is uploaded to a code repository"?

[Ryan M.]

The BSD license (http://www.opensource.org/licenses/bsd-license.php) Allows any modification to the code to be used for any reason, as long as the license notice is retained. Thus, it is close to being public domain, but you guarantee that your name will stay with the code for posterity (as opposed to the public domain, where you could remove any notices from the code).
...The BSD or LGPL is probably good for this. There are very few limits put on the use/modification of the software that way.

I also have to add that I like the way you copied yourself there... ;)

P.S. I don't like the default code style much.

[Astronouth7303]

I say that uniformity. And the basic layout (header comments and such) is pretty good. I usually don't keep the bottom bit, though.

Sorta like MPLAB!

[Joe Ross]

Well, Dr. Joe just said I volunteered for the licensing portion of the committee. I'd be willing to accept with the disclaimer that IANAL* although I've been told I should be one at various points. My other disclaimer is that I need someone to check to see that I don't make any more copy and paste errors ;)

*IANAL - I Am Not A Lawyer

[Mike Ciance]

that would be very helpful to both new and old teams. we had a ton of trouble programming our big arm this year (i know because i was one of the programmers) we had a real hard time figuring out how to properly bring in the analog inputs and use them in the code, the booklets we got had nothing about analog! :ahh: