Welcome to the Second Life Forums Archive

These forums are CLOSED. Please visit the new forums HERE

Everyone should read this.

Justice Monde
Boatbuilder
Join date: 13 Jul 2003
Posts: 78
08-12-2004 09:10
You over-commented your diatribe.

-J
_____________________
JMonde Boatworks - Period ships and bad-ass powerboats - Myrtle 118, 118
Ama Omega
Lost Wanderer
Join date: 11 Dec 2002
Posts: 1,770
08-12-2004 09:48
AAAHHHH For the love of whatever diety you hold sacred (or /dev/null if your athiest) ....

The purpose of a comment is to add clarity to code where needed.
CODE
x=3; // assigns the new value of x to be equal to the number 3.
That is rediculous. Very seriously. It is inanely obvious that what you are doing is assigning 3 to x. That is what the code says. If you had done this:
CODE
x = 3; // We use three because x counts the elements of a vector
(Assuming this line was in a different program where this made sense etc.) Then I would be 'oooh ok. that is helpful'.
I think the following is so true and needs to be quoted:
From: someone
I am going to tell you a big secret about computer programming. You have to promise not to tell anyone, ready? Here it is:

Programs are not for computers to read, they are for people to read. Computers read assembly and byte code. People read source code.

Keep this in mind, and you'll be fine.
What this means is that the code you write is the comments. The code is the comments. Comments are extra comments, the code is the comments.

Now if you had to program in machine code then your comments would be fine:

CODE
1100101011010010 // This assignes x to be 3

Woah! Cool, the comment told me something I couldn't easily discern from looking at the code.

That is why we program in high level languages. We program in languages where the action of the code is human readable. You don't need to add redundant comments for it, and doing so makes your code far less readable.

Here is the most comments you should ever put in the script you posted, with the exception of using this script for people who have never programmed before:
CODE
// This program adds 3 to a value and prints the result.
// Created by wizzie Baldwin 08-07-2004

// GLOBAL VARIABLES //

int sum; // This will hold the sum of the two numbers


// GLOBAL FUNCTIONS //

// This function adds a and b and returns the result.
int add(int a, int b)
{
return (a+b);
} // end of add


main()
{
int x;
x = 3; // This is the number we will add to 3

sum = add(x,3);

printf("The sum = %d\n",sum);
}// end of main
In other words:
The purpose of a comment in general should never be to teach someone how to program.
The exception of course is if the purpose of the script / code is to teach someone how to program.
_____________________
--
010000010110110101100001001000000100111101101101011001010110011101100001
--
Wednesday Grimm
Ex Libris
Join date: 9 Jan 2003
Posts: 934
08-12-2004 10:49
From: someone
Originally posted by Ama Omega
What this means is that the code you write is the comments. The code is the comments. Comments are extra comments, the code is the comments.


Close, but what I actually meant is that code is for people to read. Function and variable names are for people structure and indenting are for people.

It is a stone-cold promise that two weeks from now you will not remember what you were thinking when you wrote something, structure and comment your code with this in mind.
_____________________
Sarcasm meter:
0 |-----------------------*-| 10
Rating: Awww Jeeze!
Wednesday Grimm
Ex Libris
Join date: 9 Jan 2003
Posts: 934
08-12-2004 10:55
This is how I would comment the sample program.

CODE
// This program adds 3 to a value and prints the result.
// Created by wizzie Baldwin 08-07-2004

/**
This will hold the sum of the two numbers. We need a global variable for this because [very good reason to do something this silly]
**/
int sum;

/*
This function returns the result of adding a and b, because [really good reason why you need a function to do this]
*/
int add(int a, int b)
{
return (a+b);
}


main()
{
int x;
x = 3;

sum = add(x,3); // see comments for add()

printf("The sum = %d\n",sum);
}

Because you need comments not for the stuff that is obvious from looking at the code, but for the exceptions. Stuff you had to figure out, and would have to figure out again if you didn't leave yourself a note.
_____________________
Sarcasm meter:
0 |-----------------------*-| 10
Rating: Awww Jeeze!
Francis Chung
This sentence no verb.
Join date: 22 Sep 2003
Posts: 918
08-12-2004 16:49
Ooh, I wanna play too.

This is how *I* would comment this code.

CODE

// Fran was here
// If you can't understand something this trivial without comments, you don't deserve my code.

int sum;

int add(int a, int b) { return a+b; }

main() {
int x = 3;
sum = add(x,3);
printf("The sum = %d\n",sum);
}


BTW, I really need to get one of those sarcasm meters....
_____________________
--
~If you lived here, you would be home by now~
Wednesday Grimm
Ex Libris
Join date: 9 Jan 2003
Posts: 934
08-13-2004 10:18
Oh, I'll be *sure* to send you one *right* away.
_____________________
Sarcasm meter:
0 |-----------------------*-| 10
Rating: Awww Jeeze!
Strife Onizuka
Moonchild
Join date: 3 Mar 2004
Posts: 5,887
08-13-2004 10:41
yawn isn't this thread dead yet?
_____________________
Truth is a river that is always splitting up into arms that reunite. Islanded between the arms, the inhabitants argue for a lifetime as to which is the main river.
- Cyril Connolly

Without the political will to find common ground, the continual friction of tactic and counter tactic, only creates suspicion and hatred and vengeance, and perpetuates the cycle of violence.
- James Nachtwey
Wednesday Grimm
Ex Libris
Join date: 9 Jan 2003
Posts: 934
08-13-2004 12:49
From: someone
Originally posted by Strife Onizuka
yawn isn't this thread dead yet?

No, people keep posting in it.
_____________________
Sarcasm meter:
0 |-----------------------*-| 10
Rating: Awww Jeeze!
Eggy Lippmann
Wiktator
Join date: 1 May 2003
Posts: 7,939
08-13-2004 12:58
*bump* - I'm so evil :D
Darwin Appleby
I Was Beaten With Satan
Join date: 14 Mar 2003
Posts: 2,779
08-16-2004 11:14
Hey Wizzie, I have something funny to share.

Mostly everyone here ONLY talked about hte first half of your post (comments, etc...) and never made it to the bottom half, about permissions and how to improve the forums. I'll explain why I think this happened in a way I think you'll find easy to understand.

THE LINES OF CODE IN YOUR POST:

llCommentsAreGood
llCommentsHelpPeopleLearn
llPermissionsAreConfusingPleaseHelp
llForumIsForLearning
llIWantToImproveForum

COMMENTS OF YOUR POST:
THE FREAKING CRYPTONOMICON YOU INCLUDED TO MAKE THAT POST LONGER THAN A "LEARN VISUAL C# IN 30 DAYS BOOK"

kthx
_____________________
Touche.
Maximus Zander
Registered User
Join date: 30 Apr 2004
Posts: 55
09-01-2004 02:58
Commenting is good if you can separate it as much as possible from the actual language that we use (LSL).

Reading the a script with the editor makes it easy to separate from the code.
Paste:ing the code on forum often makes it unreadable because its the same color.


//Be careful not to comment too much
llSay(0,"Hello World";); //This will output Hello World to the channel 0 with the function of llSay.
//It can be quite hard to find the code if there is more comments than code.
Azelda Garcia
Azelda Garcia
Join date: 3 Nov 2003
Posts: 819
09-01-2004 05:29
CODE

// This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comment // This is a comm...
_____________________
Ken Virgo
Fighting GURU
Join date: 19 Jun 2004
Posts: 62
help the newbies....
09-01-2004 10:44
Almost everyone here is rambling about someone elses post...wahhh wahhh....build a bridge and get over it. How about helping the people who need it? Some people cant understand it no matter how you put it to them in words and need to be shown. Some people learn better by doing and not by reading. Its called hands on. Remember..... every single person was a newbie before...so try to help the ones that need it.:cool:
Ice Brodie
Head of Neo Mobius
Join date: 28 May 2004
Posts: 434
09-04-2004 05:59
CODE
default
{
state_entry()
{
llSay(0,"Comments... we don't need no stinkin comments.");
}
}


Actually if you see a comment in my code, it means I was confused by it and needed a note. I've also been said to use poor tab dilimination in other languages, but I write my code for me... Note that I don't teach a coding class at USL for this reason.

Though if you ask me about my program, I can probobly explain anything in it to you with a summary of what it's supposed to do.

example: The above code says something funny when it's compiled, or something sends it into the default state.

But 16 color glossy photographs with a paragraph on the back of each one is a bit too much when
//this stores the current dataserver key, and should be global.
says what needs to be said, I agree, functional and simply descriptive comments.

If the comment's longer than the code and it can be said another way, it's likely that it needs to be rewritten. But hey, English isn't really my strongest language.
_____________________
Strife Onizuka
Moonchild
Join date: 3 Mar 2004
Posts: 5,887
09-04-2004 22:39
Ice I remember somewhere mentioned on the GNU homepage that they recommend against using the GNU Public Licence on anything that is shorter then the licence it self. So i have to agree; 99% of the code i write is for my self or for people who can't code, so no comments (unless it's some complicated abstract interface i dreamed up...). One comment per conditional or function is the most i generaly ever use.
_____________________
Truth is a river that is always splitting up into arms that reunite. Islanded between the arms, the inhabitants argue for a lifetime as to which is the main river.
- Cyril Connolly

Without the political will to find common ground, the continual friction of tactic and counter tactic, only creates suspicion and hatred and vengeance, and perpetuates the cycle of violence.
- James Nachtwey
1 2