View unanswered posts | View active topics It is currently Thu Jul 31, 2014 3:37 pm






Reply to topic  [ 8 posts ] 
Please Advice: Good Programming conventions to teach 
Author Message
Novice

Joined: Sun Feb 04, 2007 12:48 am
Posts: 69
Location: Australia
Post Please Advice: Good Programming conventions to teach
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


Sat Dec 06, 2008 4:13 pm
Profile
Professor

Joined: Fri Sep 19, 2008 1:22 am
Posts: 200
Post Re: Please Advice: Good Programming conventions to teach
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.

Code:
/////////////////////////////////////////////////////////////////////////////
//
//                          Arcade
//
// Arcade mode uses just the right joystick to drive the robot.
//
/////////////////////////////////////////////////////////////////////////////
void Arcade(int x, int y)
{
    int powY;
    int powX;
    int powRightMotor;
    int powLeftMotor;

    // convert joystick -128 to 127 range to -100 to 100 for powering motors
    powY = scaleJoystick(y); // joystick y axis gives maximum power level
    powX = scaleJoystick(x); // joystick x axis gives turn rate

    if (powX < 0) //  if x negative, turning left; otherwise, turning right
    {
        powLeftMotor  = (powY * (100 + (2 * powX))/100); // left motor reduced for left turn
        powRightMotor = powY;                            // right motor not changed
    }
    else
    {
        powRightMotor = (powY * (100 - (2 * powX))/100); // right motor reduced for right turn
        powLeftMotor  = powY;                            // left motor not changed
    }

    SetMotors(powLeftMotor, powRightMotor);
}

_________________
Jeff McBride
Benson Robotics Club


Mon Dec 08, 2008 12:51 pm
Profile
Novice

Joined: Sun Feb 04, 2007 12:48 am
Posts: 69
Location: Australia
Post Re: Please Advice: Good Programming conventions to teach
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


Wed Dec 10, 2008 3:35 am
Profile
Moderator
Moderator
User avatar

Joined: Wed Mar 05, 2008 8:14 am
Posts: 3165
Location: Rotterdam, The Netherlands
Post Re: Please Advice: Good Programming conventions to teach
JamesD wrote:
I often find I overlook actively teaching these conventions and the kids get into bad habits that are harder to break down the track.

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

_________________
| Professional Conduit of Reasonableness
| (Title bestowed upon on the 8th day of November, 2013)
| My Blog: I'd Rather Be Building Robots
| ROBOTC 3rd Party Driver Suite: [Project Page]


Wed Dec 10, 2008 3:54 am
Profile WWW
Rookie

Joined: Sat Apr 19, 2008 11:51 am
Posts: 43
Post Re: Please Advice: Good Programming conventions to teach
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.


Wed Dec 10, 2008 4:10 am
Profile
Professor

Joined: Fri Sep 19, 2008 1:22 am
Posts: 200
Post Re: Please Advice: Good Programming conventions to teach
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;

_________________
Jeff McBride
Benson Robotics Club


Wed Dec 10, 2008 11:52 am
Profile
Novice

Joined: Sun Feb 04, 2007 12:48 am
Posts: 69
Location: Australia
Post Re: Please Advice: Good Programming conventions to teach
Thanks guys, I think the suggestions here are really good teaching guidelines.

Particularly Mightor's suggestion:
Quote:
Surely that depends entirely on how much force you apply?
:wink:

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


Tue Feb 17, 2009 11:35 pm
Profile
Expert
User avatar

Joined: Tue Oct 14, 2008 7:16 pm
Posts: 171
Location: Investigating an unidentified ship sighted in Sector 31428
Post Re: Please Advice: Good Programming conventions to teach
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.

_________________
Captain, Head programmer, School of the Arts, Silverbots Robtics Team #2890
Code:
using namespace System;
using namespace Genius;
using namespace Personality;
public ref class Nerd : Geek, IAnserable
{
    Geek::Type brainMode = Geek::Type::Programmer;
}


Wed Feb 18, 2009 1:38 am
Profile
Display posts from previous:  Sort by  
Reply to topic   [ 8 posts ] 

Who is online

Users browsing this forum: No registered users and 2 guests


You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot post attachments in this forum

Search for:
Jump to:  



Powered by phpBB © 2000, 2002, 2005, 2007 phpBB Group.
Designed by ST Software for PTF.