|
|
|
![]() |
|
|||||||
|
||||||||
![]() |
|
|
Thread Tools | Rate Thread | Display Modes |
|
|
|
#1
|
||||||
|
||||||
|
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. |
|
#2
|
|||||
|
|||||
|
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. |
|
#3
|
|||||
|
|||||
|
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.
|
|
#4
|
||||||
|
||||||
|
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
|
|
#5
|
|||||
|
|||||
|
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? |
|
#6
|
|||
|
|||
|
Re: Coding / Style Standards for sharing C code
I don't think C has enums (unfortunately).
|
|
#7
|
|||||
|
|||||
|
Re: Coding / Style Standards for sharing C code
Quote:
|
|
#8
|
|||||
|
|||||
|
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 a. Information hiding 3) Error Handling a. External status4) 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) 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. Last edited by Mark McLeod : 29-04-2004 at 11:37. |
|
#10
|
||||||
|
||||||
|
Re: Coding / Style Standards for sharing C code
Quote:
...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. |
|
#11
|
|||||
|
|||||
|
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. Last edited by Mark McLeod : 29-04-2004 at 12:52. |
|
#12
|
|||||
|
|||||
|
Re: Coding / Style Standards for sharing C code
Quote:
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:
Last edited by MikeDubreuil : 29-04-2004 at 12:50. |
|
#13
|
||||||
|
||||||
|
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. |
|
#14
|
||||
|
||||
|
Re: Coding / Style Standards for sharing C code
Quote:
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. |
|
#15
|
|||||
|
|||||
|
Re: Coding / Style Standards for sharing C code
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. |
![]() |
| Thread Tools | |
| Display Modes | Rate This Thread |
|
|
Similar Threads
|
||||
| Thread | Thread Starter | Forum | Replies | Last Post |
| heres the code. y this not working | omega | Programming | 16 | 31-03-2004 15:18 |
| Inserting Naviagation code into Default code? | actorindp | Programming | 3 | 28-01-2004 18:12 |
| Help On Coding 2K1 Controller | GregTheGreat | Programming | 9 | 05-12-2003 18:35 |
| style | srawls | Programming | 19 | 23-05-2002 17:02 |