SC2Mapster

I have an question about leaving comments. I am trying to become a rigorous comments leaver because I know that somewhere along the way I may hand sections of coding over to others and I want them to not have to look over code and wonder "wtf was he doing". However I'm fairly new to coding and likewise new to leaving comments. Ive been told the best comments could literally in English explain to someone who had no coding knowledge what you are doing with the code. In this next part I'll leave people with a bit of my code and the comments and see if anyone has some pointers to what I could do better or if I'm going to far. I'm completely open if anyone has some helpful suggestions.

    if ((gv_voteTally[0][0] == gv_voteTally[0][1]) && (gv_voteTally[0][0] > gv_voteTally[0][2])) {
	// If Easy Difficulty Votes is equal to Normal Difficulty Votes
	// and Easy Difficulty Votes is larger than Hard Difficulty Votes
        lv_tieBreaker = RandomInt(0, 1); //Sets TieBreaker euqal to a random number between 0 and 1
        if ((lv_tieBreaker == 0)) {
        // If TieBreaker is equal to 0
            gv_voteTally[0][1]=gv_voteTally[0][1] + 1; //Set Normal Difficulty Vote + 1 (increasing its number of votes by 1)
        }
        else {
	// If TieBreaker is equal anything else
            gv_voteTally[0][0]=gv_voteTally[0][0] + 1; //Set Easy Difficulty Vote + 1 (increasing its number of votes by 1)
        }
    }
    else {
    }

PS. Is a good idea to try and leave comments in the GUI? from what I can tell comments don't seem to carry over

@alderis: Go

Well you dont really need comments for each line....

but comments that explain the point of the logic if its complex logic are nice.

Also if you have multi dimensional arrays its nice to comment what each index of the array stands for.

If your using lots of variables its nice to explain what the variables are and or what they represent.

Don't comment unless it's necessary.

if( x == 0 ) // if x is 0

is just unnecessary. Anyone worth their salt can read an if statement.

Now, when you're dealing with perhaps...

struct myData
{
    fixed x;
    fixed y;
    fixed z;
    fixed r; // facing in radians
};

then a comment might be appropriate, because the definition of "r" isn't readily obvious.

Basically:

Quote:

Ive been told the best comments could literally in English explain to someone who had no coding knowledge what you are doing with the code.

That's a load of crap.

glad to hear some input back about this

Quote from MotiveMe: Go

Basically: Quote:

Ive been told the best comments could literally in English explain to someone who had no coding knowledge what you are doing with the code.

That's a load of crap.

glad to hear it. When someone told me that I was a bit dubious because to do comments like that is very time consuming. He assured me it was the case but I'm positive after hearing from you guys that he is just spouting insanity.

Yea hah.
Everyone with a little knowledge of coding (and others shouldn't try to understand your scripts in the first place) won't need most of these comments.
Instead, you should point out important stuff which can't be seen immediately.

For example:

    int b = 5;  //variables with not selfexplanatory names should be explained if it isn't obvious.
                 //For example I always use 'i' for counters. No need to comment it anymore.
                 //But I don't know what 'b' could be :x

    int[10] gv_SomeArray;   
 
   // It's rather obvious in this case, but leave a comment to make sure that people are aware
   // of limits for parameters: int index must be between 0 and 9.
    void SetIndex(int index, int value){
         gv_SomeArray[index] = value;
    }

    void SomeTrigger(){
        SetIndex(12, 6); //In this case we'd kill the stuff.
    }


    void AnotherTrigger(){
        int i=0;
        //Constructs like this should contain an explanation of what they're used for.
        //Not entirely detailed, but enough for people to understand where to look for
        //what they're looking for.
        while(i<gv_blah){
            DoSomeStuff();
            ModifySomeOtherStuff();
            if(someComparison){
                MoarStuff()
            }
        }
    }

Well, this is what I learnt in Software1: At the beginning of each function you should state expected parameters and outcome. But that's mostly if you don't care if the guy reading it would understand how the function works, only what it does. The beauty of modular programing.

I've heard it put like this: "Comments don't tell how you're doing something, but what you're doing." Sort of like answering the question, "Why this block of code?"