2012 Programming Protocols

Commenting:
1) All comments will be full and complete sentences, complete with proper punctuation and grammar. It's hard to be perfect in terms of the language used, but just try to be clear, concise, and informative.
2) There must be one comment per distinct section. Look at code I've written for an example of what a distinct section is (and I'll admit that I also skimp on the comments a bit from time to time). Just make sure that you don't go more than a few lines without commenting, and just try to make all of the code you write easy to understand.

Code layout:
1) Indentation is important to keeping everything neat. The code I've written at the time that these protocols were posted represent the way in which indentation should be performed. Also, while I sometimes leave out braces ({}) when they aren't necessary, you needn't worry about that detail. Just put them where they should go, as you'll never be penalized for putting them somewhere that they aren't needed (well...you will, but only by having your code be--maybe--a bit slower. Just don't worry about it).
2) When a particular task is repeated many times, or a particular code line, and only the values or variables change, the task should be made into a function. We'll talk about functions one day, maybe if someone reminds me, but if you understand how to make an use them, you should be trying to make things into generalized functions as much as possible.
3) Whenever a constant is used--a constant being a number or string typed directly in the code--you should use a macro. For example, macros are used instead of typing the joystick button numbers directly into the coder, and are also used in place of the port numbers. This allows us two advantages: firstly, if the number changes, we need only change the macro instead of searching through the code and changing each instance, hoping that we don't miss anything; secondly, it makes the code easier to read as what was once simply a meaningless number is now an actual name or phrase that someone can understand and use to infer its purpose.

General:
1) Variable names, as we mentioned, should be full and directly imply the purpose of the variable. For example, instead of calling a variable x or enc_dist, we should name it encoderDistance, as that makes it clear to someone reading the code that the variable stores a distance from an encoder. Notice that the first word is always lowercase, and the remaining words are uppercase. This is true even with many words, like encoderDistanceAsCalculatedFromPIDLoop--which is a bad example, as it is a case of becoming TOO specific with your variable name, but you get the idea. Generally, a noun/adjective or noun/noun pair is used, but I'll leave it up to you. For functions, each word should be capitalized, like TrackSteering or GetEncoderValue. Macros should be all uppercase, like LEFTJOYSTICKPORT.
2) Be careful with your math and order of operations. More importantly, watch your types. For example, if x and y are "int"s, calling lfMotor->Set(x/y) might not work how you expect, because x/y will never evaluate to a fractional value--it will round to an integer. One solution is to make both values floats, so that x/y can evaluate the way you want. Another option, though slightly more complicated, is to convert them to floats at the time you use them. You do that by putting (float) in parenthesis, like that: lfMotor->Set((float)x / (float)y). It's easier just to make them floats in the first place, though. The same can be done the other way around by putting (int).
3) Debugging is important. Always write just a few lines of code, then test and fix the problems before writing more. This makes it easier, if a problem occurs, to determine what piece of code caused the issue. If you need help fixing an issue, ask someone or post on the forum (and in a worst-case scenario, you can feel free to call my house and I'll help if I'm home).

Redundancy:
1) Backups should be made at the end of each day. Firstly, the current version of code should be copied to the file under "Robotics 2012/Code". Just copy the text and paste it directly in the file over top of the old code. Then, a new text file containing the same copied text should be made under "Robotics 2012\2012 Code Backups". This file should be named "BackupN - xxxxx.txt", where N is the next number in order, and xxxxx is a description of the changes made. Also, feel free to update the date on the code file at the top (and feel free to put your name there, if you'd like). Also, you may take a copy of the code or the backups home with you on a drive if you would like to look it over or just keep another copy. The more backups, the better
2) Always plan for errors when you test things. If you've made a change to the steering code, be prepared for the wheels to spin without end and be ready to disable the robot or something to prevent damage. Sometimes the robot will run away once you press Enable and drive itself into a wall or desk. Therefore, you need to be ready for something. Also, major code changes should be checked with a more senior programmer before it is tested, especially if there is a danger--at least, for the first little while where the newer people are less used to the process.

Documentation:
1) This is something I've debated. We might keep a hand-written or printed out list of the various variables, macros, and functions we've created to track and explain what everything does. At the very least, it is important for us to be able to remember what ports are used for which peripherals, and which buttons on which joysticks execute which command.

Finally, this is the link to the 2011 robot Wiki page. I'm not sure where the one for this year is, or if it exists, as I haven't checked. Nonetheless, we play a bit role in this years product, so we should be keeping the wiki updated