Hi All,

I’m reassessing the way I teach RobotC next year and I’m looking for tips on how others teach it and also what conventions people use. An few examples of conventions I teach would be:

1) I teach the kids to start variables names with specific lowercase letters ie b for Booleans, n for integers, f for floating point & str for string names. This helps them locate the correct variable names easily using the autotype feature. Ie nLeftSensorValue

2) Expecting students to start all their functions [void fnX()] with fn ie fnCanSearch.

3) To make things easier to read I now teach students to keep the first curly bracket of a function on the same line as the name. Then when the program is automatically formatted/indented ie Edit -> Advanced -> Format Whole File, it will be less cluttered and easier to read.

Please feel free to support or criticise (with reasoning) my choices as I don’t have a formal programming background I’m just looking for help/advise/confirmation in this area.

Thanks,
James

Here are some of the things that I teach my students:

- There is no reason to have a comment on every line of code.

- Do not use comments to repeat what the code says. Assume that the reader can understand the meaning of the code. In particular never include numeric constants in the comments that also occur in the code . In other words, don’t do this: x = 3; // Set x to 3.

- Use comments to tell the reader why you are doing something. In other words, comment your intentions and assumptions.

- It is also a good idea to comment known problems or suggested improvements.

- Simple straight forward code is ALWAYS better than clever code.

- Make the indentation and whitespace consistent throughout the program. Layout is important. Do not make the reader work hard to follow the code. Make it as easy as possible for them.

- Do not be afraid of whitespace. It makes it easier to follow and maintain the code. There is no benefit in reducing the size of the file.

- Do not allow any function to get too large. Break things into small sub-tasks to improve readibility and maintainability.

Here is a short example of a well written function. The key thing to notice is how easy it is to read and understand and how the comments complement the code rather than just repeating it.

Hi Jeff,

Thanks for taking the time to respond. Your response might be stating the obvious, to people who have been programming for a while, but as you know it is really handy to teach this sort of knowledge overtly. I often find I overlook actively teaching these conventions and the kids get into bad habits that are harder to break down the track.

Thanks
James

Surely that depends entirely on how much force you apply?

Another few things I find very useful when browsing through mine or someone else's code are:

• Function descriptions that include parameter info.
• If you are writing a library, put all the user-usable function at the top with a short description of what they do and how to use them
• A single naming convention for your variables
• Descriptive names for your variables, so no int _t1, _t2, _t3; but rather int _index, _counter, _max;
• Code that is repeated inside one function should be pulled out and put in its own function, if need be use the "inline" keyword
• Don't try to use function calls as arguments for functions, ie something like this: validate(max(get_sensor(SENSORA))); There is enough memory to go around for most purposes, so use an appropriately named temporary variable. This also makes adding a breakpoint for debugging a lot easier as well as being able to monitor this temporary variable in the variable window.
• Version your code!!! This makes going back to a previous version a lot easier if you find that you've made a BIG mistake. Put the version at the top of the file and preferably in the file name itself (if possible).

That's about all I can think of off the top of my head.

Regards,
Xander

hi,
to my opinion and to my experience there won't be a need to put "b" or "f" before the names, if the names themselves are clear and understandable.
For example:
everybody knows that sensors have Integer values (and no fp), what else should "brightness" as a light sensor value be,
or if an angle has to be calculated by sin or atan, it's supposed to be a fp, because integer doesn't make a sense,
and if a string like "abcde" is assigned to a variable, it's clear that the variable is of a string type.
If you have incremented indices, you may use i++, j++, n+=2, m--, and it also is clear that they are integers or chars (bytes).

Only in case of abstract var names like "buffer", "buf", "array", or "dummy", which are not understandable in a "suggestive manner", or if values need to be converted from one var type to another, it might be helpful to have a prefix like
string strBuf
int nDummy
float fArray[10]
int nHeading
float fHeading

So I won't recommend to make more restrictions than there are basically really needed.

I agree that type prefixes aren't always required although I do like to use "st" in front of strings. The place where type prefixes are most useful is to distinguish between different types of units such as minutes, meters, degrees and so on. It is very helpful to be able to visually tell if the math in your program makes sense. For example:

headingNew = (headingCurrent + angleChange) % 360;

cmTraveled += cmWheelDiameter * clicksEncoder / clicksPerRotation;

Thanks guys, I think the suggestions here are really good teaching guidelines.

Particularly Mightor's suggestion:


Another thing I'd like to get hold of would be a pdf/poster/jpg of a diagram or table outlining the names of different lego categories/pieces. ie Flats, bricks, beams, pins, bushes, cogs etc

Does anyone have any suggestions?

Thanks,
James

While I don't know of the existance of any such poster, you might beable to peruse the main Lego site and construct on from copying the images and names.

I would also suggest that you not over look the teaching of the standard language conventions like loops - for, while, do-while, if-else statements, and switch-case statements, all of which can be immensly powerful. Along with this don't overlook the basic tests, <, <=, etc., also and-&&, or-||, and not-!; neither should the use of arrays, both one dimensional and two dimensional, be overlooked, though you will rarely need to use two plus dimensional arrays.

I'm not a big fan of prefixing varriables, especially when there are only a few used and their purpose is clearly indicated by the name. When you start dealing with Windows/.NET programming then some prefixes are helpful but I tend to prefer indicating usage by name. Definitely teach them how to identify what kind of code can be separated into a function and what, if any values a function needs to be passed and return. As an advanced topic you can teach how to place code in seperate files based on task and include those files as necessary.

As for formatting, RobotC sucks in doing it for you which is why I like using a seperate code editor (Visual Studio 08); in general I like to put opening braces on a new line which is indented the same as the line above it and I like an indent equal to four spaces; the closing braces of a block should be equal in indent to the opening brace so that nested blocks can be followed easily. You should definitely teach consistant formatting otherwise you get this mess of text that becomes impossible to follow.

Perhaps the best thing to do would be to get a self-teaching book on C and teach the students by following the progression of the book; you can even get a free standard C compiler and have the kids do any exercises that accompany the book, particularly the ones on conditionals and loops, obviously pointing out which Windows conventions don't apply in RobotC, particularly the common C header files and function recursion, a powerful feature that unfortunately can't be used in RobotC. Just as a note, if you try to write a recursive function RobotC will just close with no warning and you won't be able to reopen it, or at least that file, until you remove the offensive function.

Hope this helps and good luck teaching in the infinite land of programming.