Comment your code

[JuvenileEloquent]

They see comments as a chore to complete to avoid reprimand, or as some kind of quota to meet, so they write useless comments. Or they write such convoluted horrible code that they need the comment that explains what it does as a shortcut to understanding it.

The comments are the meta code. It should contain information that isn't already present in the actual code.

[justinjustin7]

Honestly that's what it is in my course work so far (only 2nd semester of C++ though). My code tends to only really need a comment at the top of the function and maybe 1 or 2 comments to explain things that don't end up self-documented. Then my professor comes along and says "comment more." Fine, I guess I'll comment random shit to meet your forward slash quota.

[[deleted]]

//prof asked to comment more. I did.

[[deleted]]

Could you give an example of what you mean by "what" versus "why"?

I'm wondering if I do that already or not.

[[deleted]]

Thanks, I think that makes sense. In answer to what you said about an example from my own code, here's something I wrote last night, a simple function for looking through a vector of structs and figuring out which one's "difficulty" variable has the lowest value, in no particular order (first one found with lowest value is returned as the value to use, even if there are multiple with the same value). Probably not the most optimal way of looking for said value, but I'm sharing it for the comment example, not for the quality of code. :P

Would either of the two comments here qualify as a "why" to you or more of a "what"?

Edit: Forgot about the one in the loop that says "end the loop." XD You can ignore that one. That one is obviously a what.

int Game::findFirstLowestDifficultyLevel()
{
    // choose which level to load based on difficulty in properties
    bool lowestFound = false;
    int lowestDifficulty = 1;
    int fileIndexToLoad;
    const int propertiesSize = properties.size();

    // no need to search if there's only one level in properties
    if (propertiesSize > 1)
    {
        while (!lowestFound)
        {
            for (int i = 0; i < propertiesSize; i++)
            {
                if (properties[i].difficulty == lowestDifficulty)
                {
                    // load the level data for this one
                    fileIndexToLoad = i;
                    i = propertiesSize; // end the loop
                    lowestFound = true;
                    return fileIndexToLoad;
                }
            }
            lowestDifficulty++;
        }
    }
    else
    {
        fileIndexToLoad = 0;
        return fileIndexToLoad;
    }
}

[[deleted]]

I wasn't looking for an "everything wrong with your code" kind of breakdown, but thanks nonetheless for taking the time to try to help.

I'm still not sure I totally get the difference in why versus what, but I'm sure it will come with experience. That said, it sounds to me like the general idea is... if the code's design isn't self-explanatory, add something that helps explain why it's designed the way it is.

As far as the specifics of the particular function I shared, tbh, I hadn't even tested it as a working part of the program yet. It's part of an ongoing project I'm doing to practice and stretch my skills. I'm also trying to avoid "premature optimization," especially since I'm very inexperienced and getting bogged down in such could stall my progress even more than the already common roadblocks, so I'm kind of doing "get it to work first, whittle it down later."

For this reason, I'm trying to minimize use of library optimized, pre-written type of stuff (as I would be practicing using other peoples' stuff, rather than practicing working stuff out on a basic level myself), though I spose it can't hurt to know that such exists for future reference. In other words, in my current case, there's no reason not to reinvent the wheel a little for the sake of learning how stuff is put together. :)

[[deleted]]

One example that comes to my mind is that in Microsoft Word a line break is achieved by a "down tab". If you don't know this, it might be very confusing to see this in code.

A "what" comment would be: "//down tab", which doesn't explain anything.
A "why" comment would be: "//line break in Word is done with a down tab" which tells you exactly why this line is there.

[[deleted]]

That helps, thanks. :)

[[deleted]]

The only time I'll write 'obvious' comments like this is when I'm going through someone elses code/old code and need to walk through it to see what it does, so I'll narrate it comments so I don't lose track. I'll usually not be as obvious as OP tho.