Computer Science Canada

Using Comments
Author:  batman [ Fri Mar 03, 2006 5:00 pm ]
Post subject:  Using Comments
In this tutorial you will learn how to comment your code properly.

How do you comment code?

There are two wyas of commenting code.
!. Using % sign. The percent sign is used for one line comments.
2. To write multiple lines of code use the asterisk and backslash. In the begining of a long comment place "/*" in front and at the end place "*/".

When should you comment?
In the beginning of each program you should write down three things.
1. Program Description
2. Written By
3. Last updated

Heres an example:
code:

/* Program Description: this prgram outputs something.
Written By: Batman
Last Updated: March 3, 2006 */


Through out the code you should use "%" single line comments for parts of your code that are difficult to understand by the user.
Heres an example:
code:

var name : string %this is were you can put a comment
put "What is your name?"
get name:*
put "Your name is ", name 


And last but not least you have to divide your code into 4 sections using comments.
1. Variables and Constants
2. Input
3. Calculations
4. Output

Keep in mind that not all programs have every single section.
Heres an example:
code:

%Variables
var name : string %this is were you can put a comment

%Input
put "What is your name?"
get name:*

%Output
put "Your name is ", name 


Know that you know this make sure you comment your code properly it's very important.
Author:  Delos [ Fri Mar 03, 2006 5:51 pm ]
Post subject: 
Thanks for the tut...[wait for it]...but:

- Please indent your code (it's only bearly noticable here though)
- "!." != 1.
- "Too write" != "To write"
And most importantly:
- This tut already covers this topic. Please consult the Turing Walkthrough next time you feel the urge to write a tut to ensure that it has not already been covered (or if it has if it needs updating. (Consult Improving Tutorials for this purpose).)
Author:  batman [ Fri Mar 03, 2006 6:05 pm ]
Post subject:  Commenting
I know it's already been done but my tutorial explains more and expands more on whats there. Very Happy
Author:  md [ Fri Mar 03, 2006 9:35 pm ]
Post subject: 
You don't need to split things up in to 4 sections. It may be helpful for you, but it's definitely not nessessary. When learning other languages that convention will actually get you into a fair bit of trouble.
Author:  [Gandalf] [ Sat Mar 04, 2006 8:43 am ]
Post subject: 
Delos wrote:
- "!." != 1.

Being confusing as ever, I see. Smile

For Turing, it would be much more useful to split your code up into:
1. Global Variables/Constants
2. Classes
3. Procedures/Functions
4. Main Code/Loop
1 and 2 are interchangable, but this way works better.

Also, a method of doing multi line comments which I like (and it seems to be used elsewhere) is:
code:
/* Line 1
 * Line 2
 * Line 3
 */
 
%OR

/**
 * Line 1
 * Line 2
 **/
Author:  batman [ Sat Mar 04, 2006 9:26 am ]
Post subject:  Commenting
1. Global Variables/Constants
2. Classes
3. Procedures/Functions
4. Main Code/Loop

You could split up your code this way but for beginners it is best to split your code this way:
1. Variables and Constants
2. Input
3, Calculations
4. Output
Author:  Booya [ Sun Mar 05, 2006 7:03 pm ]
Post subject:  Tutorial
So you're suppose to comment your code?
Oh ok!
Author:  [Gandalf] [ Sun Mar 05, 2006 7:14 pm ]
Post subject: 
[url=http://www.99-bottles-of-beer.net/language-ook!-515.html]Ook![/url]
lol, couldn't help it.

batman, it would be much more benefitial if you got into the habit of organizing your programs that way. If you don't understand procedures/functions learning another language after Turing will be very difficult.
Author:  batman [ Sun Mar 05, 2006 7:24 pm ]
Post subject:  Commenting
Booya you should comment every code, it makes it easier for the user to understand. And thanks for the information Gandalf, I didn't know that. Very Happy
Author:  [Gandalf] [ Sun Mar 05, 2006 7:32 pm ]
Post subject: 
No problem.

Yes, commenting your code is good, but don't over-do it. Things that are self-explanatory, where the code is obviously doing something, don't require a comment. For example:
code:
var name : string := "Gandalf"  %Creates name, a string variable which holds the name Gandalf.

is obviously redundant.
Author:  Booya [ Sun Mar 05, 2006 7:34 pm ]
Post subject:  Commenting
Ok booya and gandalf I didn't know that! Thanks a lot! Very Happy
Author:  batman [ Sun Mar 05, 2006 9:24 pm ]
Post subject:  Booya
Booya and Gandalf? Confused
Author:  Booya [ Sun Mar 05, 2006 9:35 pm ]
Post subject:  Info
Oh my bad!
Srry!
Thanks Batman and Gandlaf for the info!
Author:  Cervantes [ Sun Mar 05, 2006 9:52 pm ]
Post subject: 
Booya and batman, stop spamming. You have been warned.

:


You can syndicate this boards posts using the file backend.php or view the topic map using sitemap.php.

Terms of Use | Privacy Policy