// and finishes at the end of the line
• The multiline comment that starts with a
/* and ends with a
*/ The following is an example using both forms of comments:
In this book, I mostly stick to the single-line comment format.
Good comments help explain what is happening in a sketch or how to use the sketch.
They are useful if others are going to use your sketch, but equally useful to yourself when
you are looking at a sketch that you have not worked on for a few weeks.
Some people are told in programming courses that the more comments, the better. Most
seasoned programmers will tell you that well-written code requires very little in the way
of comments because it is self-explanatory. You should use comments for the following
reasons:
• To explain anything you have done that is a little tricky or not immediately obvious
• To describe anything that the user needs to do that is not part of the program; for
example,
// this pin should be connected to the transistor controlling the relay • To leave yourself notes; for example,
// todo: tidy this - it’s a mess This last point illustrates a useful technique of
todo s in comments. Programmers often
put
todo s in their code to remind themselves of something they need to do later. They can
always use the search facility in their integrated development environment (IDE) to find
all occurrences of
// todo in their program.
The following are
not good examples of reasons you should use comments:
• To state the blatantly obvious; for example,
a = a + 1; // add 1 to a .
• To explain badly written code. Don’t comment on it; just write it clearly in the first
place.
Conclusion This has been a bit of a theoretical chapter. You have had to absorb some new abstract
concepts concerned with organizing our sketches into functions and adopting a style of
programming that will save you time in the long run.
In the next chapter, you can start to apply some of what you have learned and look at
better ways of structuring your data and using text strings.
