Let's Make Robots! | RobotShop

Newbie’s guide into programming - 00000101 - Commenting your code

Helps newbies to learn how to program

So, what are comments? They are exactly what they appear to be from their name. Comments or remarks are text that programmer put into code to improve readability of the program. Beginners usually do not pay enough attention to commenting their code as they are so excited by new things they learn. And then it is becoming a bad habit to leave their code without comments whatsoever. Very often happens that person coming back to edit their code after a week or two hardly understands what is going on in the code. On the contrary, even person for the first time looking at the code which is well commented, can pretty fast pick up the idea of the particular snippet and modify the code with little effort.  Others think that remarks take up too much of memory, but they are wrong. Remarks are ignored at the time of compilation, so put a good paragraph of comments in if you feel it will help you to decipher the code later!

Ok, you are now determined to comment almost every single line of your code from now on and till the end of time! But, how do we do that? Actually you have already seen examples of comments in two previous chapters. Anyway, comments can be single line or multiline. Let’s see how they are implemented in Picaxe and Arduino.

First, the Picaxe Basic.

Single line comments can start with any of these markers:

·         – (apostrophe)

·         ; - semicolon

·         Word REM

Multiline remarks have to be enclosed into #rem - #endrem clauses. Note that opening clause has to begin from new line. Let’s see some examples of Picaxe remarks:

'this is a comment

pause 1000 ;remark can start straight after instruction

low 4 rem this is another single line remark

 

#rem

And this is a multiline one

You can write whatever you want in here

And you do not need to put ‘ or ; before each line.

When you have finished, simply write

#endrem

 

Arduino C is a little different. I’d say it is simpler and more flexible. You can use one of two structures:

·         // (double slash) Is a single line syntax

·         /* and */ clause. 

The /*...*/ clause can be used not only for making multiline remarks, but also for inserting comments inside the actual code lines. Let’s see how it’s done along with other examples for Arduino C.

//this is a single line remark
int a; //comment can be used as usual
/* nice 
multiline comment here */
int b; /*can start 
like that */
int /* can even go in here! */ c;

 

 

I will try to give more of specific tips on commenting your code as we progress through chapters.

Now you know how to comment your code, and I insist that you make commenting your code a habit, starting right your first program!

 

See other chapters of this series here.

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

that commenting can also be used to block out sections of code?

PS-Thanks for spending the time to write these tips.

Thanks for sharing your skill and experience with us my friends :) It's always interesting reading and learning from you.

Cheers

Thank you birdman and Voltar for adding valuable information! :D