Advice from one newb to all the others

Hmm, it's a bit rich me offering advice when I had never seen a Arduino a month ago.. but I have been programming since 1974 when I learned Fortran.

Here are two bits of advice....

The first bit is, put comments in the sketch. Put lots of comments in. They don't take up any room since the compiler zaps them anyway so they aren't lurking in the Arduino. Comments help you remember wth you were trying to do at 3am when you read the code the next day. But, maybe more important as far as the Forum goes, they help our fellow Arduiners try to figure out what we meant when they try to help us with our code.

On the subject of comments, remember they are a debugging tool too. If you suspect the problem is in a certain area of code, bypass that code with a /*..... */ or a bunch of //s to see if the problem goes away. In the old days of BASIC, a comment line started with the word REM for REMark, so this technique is still known to Old Timers as "remming it out".

Second, use the serial monitor to help debug faulty code... I put loads of lines like Serial.print("Inside the middle nested if") so that if somethng inside my "if" isn't working I can at least see if I got there in the first place. If you're not sure a value is incrementing correctly, print it out: Serial.print(myVal) to see if your arithmetic is correct. (Remember to take these lines out later, or comment them out so they can be re-instated easily if you get more problems)

Good advice. I do that stuff, and it helps me get things going faster.

2 cents, use LED's and set them up to toggle when entering different parts of code. I have a dozen with resistors soldered on to a clipped lead so they plug into breadboards easily. Its handy when you cant afford to slow your program with a serial print, but you want to see if or when a chunk of code is actually firing, or when dealing with external logic chips.

Osgeld: I have a dozen with resistors soldered on to a clipped lead so they plug into breadboards easily.

I bought 10 just the other day to do exactly that too. I'm thinking of soldering them into an IC holder...

regarding leds as a debugging tool, i posted a topic a few days ago where i had used analogwrite from a single pin to drive four different indicator leds. Its not limited to four, it could easily be expanded to a few more. The only advantage is when you are short on pins, which lets face it is most of tne time.

Regarding comments, dont use them as a cover for a lazy naming convention i.e. The following comment and code -

// set output throttle level to input throttle level minus throttle intervention level
A = B - constrain(C,0,B);

Is lazy and will be hard to maintain in future compared to -

// apply intervention to the throttle output 
unThrottleOut = unThrottleIn - constrain(unThrottleIntervention,0,unThrottleIn);

Its a contrived example but your code should explain itself through well worded variable and function names, the comments should explain the business/project reason for a section of code. If you need comments just to remind yourself what a section of code is for, you should consider rewritting the section of code with more self explanatory naming i.e. Get into the habit of long and meaningful names for everything.

Just a suggestion.

Duane B

I second (and third) the call for debug prints.

A lot of starters are put off by the extra work involved and the fact that it isn't needed in the finished product, but I counter by saying you wouldn't put up a house without scaffolding.

We can't get help on a post that doesn't get read, so some kind of clue in the title is likely to entice someone who might be able to help, to read the thread. "I have a problem" will get trumped by "How do I decode the pulses from an XYZ" any day....

It does occur to me that it takes somewhat less time to use a descriptive name rather than a comment… takes 2 //ess characters…

Doc

For me comments are very important. Excepting perhaps a 10-line program to test a point.

  • Describe the program, what it does, who wrote it and when
  • For bigger projects, assign a version number, and describe what changes were made in subsequent versions
  • Describe any assumptions you are making ... you may forget what they were later
  • Describe how to connect hardware (eg. "connect light sensor to A3")
  • Describe other hardware issues (eg. "use 4.7K pull-up resistors on SDA and SCL")
  • If you found, after painful trial-and-error that X works, and Y does not work, describe why you are doing X and not Y.
  • Don't state the bleeding obvious (eg. "assigning 5 to i here")
  • Put comments at the end of blocks (eg. " } // end of while loop")
  • Describe what functions are doing, what arguments are expected (if not obvious) and what they return (if not obvious)
  • If non-standard libraries are used, state where to find them (eg. a URL)
  • For "configuration" constants, state an expected range, and warn what might happen if that range exceeded.
  • If timing is important, say so. (eg. "must complete quickly")
  • If something you are doing is not obvious, explain why. (eg. "fill buffer with zeroes in case X happens")
  • If you are using some external algorithm (eg. CRC check) give a link to where details might be found
  • If the order of instructions is important, say so (eg. "must clear this flag last in case another interrupt occurs")

Developer pal of mine never uses comments.... he says if it was difficult to write it ought to be difficult to read :D

Even for him, huh? Can't be very productive.

Spend enough years at it and the code -is- the comments, or at least the only ones to trust.

Sorry but I got burned enough times in my first years working on OPC (Other People's Code) where the comments never kept up with the changes made before I ever saw it. Not only that but while the comments might have triggered something in the memory of the original writer, any real explanation of whole sections was not related in the deadline-induced shorthand used. And funny enough, the fixing was always a rush job. Ever work on code that people are using each new fix as soon as you do it? I cut teeth doing that.

Lastly -- for me to explain how and why right-brain logic-based algorithms are there can take many lines of left-brain text to explain poorly. IOW, it took too much time and drained -far- too much creativity for whole explanations to be practical, and yet it's clearly right there in the code.

From the old (late 70's - early 80's) Real Programmer's Joke Sheet: If you make a language that allows programmers to write in English, you will discover that real programmers can't write English.

Yeah sure, I do put comments in like // this is to keep buff[] from overflowing and the like. But I call those hints. They don't explain more than they do.

@GoForSmoke: unfortunately I have to agree. Poor comments are worse than no comments at all. In the end the truth lies in the code. The issue is that sometimes even the original author puts in the wrong comments because he does not understand its own code.

Nick, all good points, but I struggle with this one:

Put comments at the end of blocks (eg. " } // end of while loop")

If the code in a function is long or complex enough to need this, better to split it into separate functions I think.

In even a modest length piece of code, it is easy enough to get distracted and not notice where functions end for example ...

void setup ()
  {
 ... 10 lines here ...
  } // end of setup

void loop ()
  {
 ... 10 lines here ...
  } // end of loop

... other stuff ...

If you want to add another line to the end of setup, seeing "end of setup" is a nice confirmation that you are at the right curly bracket.

Similar remarks apply to ifs within a while, or nested ifs.

[quote author=Udo Klein link=topic=112308.msg845132#msg845132 date=1341143453] In the end the truth lies in the code. [/quote]

Every now and then we see this:

timeout = 5000;  // timeout after 10 seconds

Is the code wrong, or the comment wrong? It's a point to investigate.

That last one is especially good. I wouldn’t trust either.

How not to name your thread for maximum response...