Using Comments

[batman]

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.

[Delos]

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).)

[batman]

I know it's already been done but my tutorial explains more and expands more on whats there.

[md]

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.

[[Gandalf]]

Delos wrote:

- "!." != 1.

Being confusing as ever, I see.

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  **/

[batman]

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

[Booya]

So you're suppose to comment your code?
Oh ok!

[[Gandalf]]

[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.

[batman]

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.

[[Gandalf]]

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.

[Booya]

Ok booya and gandalf I didn't know that! Thanks a lot!

[batman]

Booya and Gandalf?

[Booya]

Oh my bad!
Srry!
Thanks Batman and Gandlaf for the info!

[Cervantes]

Booya and batman, stop spamming. You have been warned.