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.
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?
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.
[font=Times New Roman][size=3]1) Use ANSI C standard[/size][/font]
[font=Times New Roman][size=3]2) Design Considerations
[indent]a. Information hiding
b. Context based control
c. Object oriented programming
d. Modular solutions
e. Memory allocation
[/indent]3) Error Handling
[indent]a. External status
b. Debugging tracebacks
c. Programmer debugging
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)
Avoid duplication of purpose
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)
Naming conventionsa. Functions
b. Macros
c. Typedefs
d. Defines
e. Includes
f. Project Files
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[/size][/font]
[/indent]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.
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?
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.
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.
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.
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)
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.
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.
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 ;).
I 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.
Brandon, don’t you love it when people volunteer you for more work? (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?
(And I think maybe a moderated forum and an associated white paper section would be good.)