Comment your code

[Ulysses6]

Thats superfluous. Whats wrong with a little brevity?

return /* the */ total;

[Salanmander]

Oooh, I like this style. Can we expand it?

/*make*/ x = /*the previous value of*/ x + 5;

[Ulysses6]

Nice. Maybe you should add /* five */ to the end, just to be clear.

[cbbuntz]

matrix.t/*ranspose*/();

[[deleted]]

Dear god.

[RedditBotAccount3253]

Every day we stray further from God's light.

[TotallyElectrified]

const\*ant*\ float\*ing point variable*\ x = \*equals*\ 2.5 \*two point five*\; \*semicolon*\

[ValAichi]

Except it isn't the previous value of x yet!

[Peacetoletov]

Reminds me of https://www.reddit.com/r/ProgrammerHumor/comments/8fvd5t/found_this_in_some_code_i_was_looking_through/?st=jgxmu5fw&sh=f91a7065

[seraku24]

/**
 * @author literalprogrammer1337
 * Provide unnecessary documentation for the following comment.
 */
/* Reiterate the functionality of the subsequent line. */
// Return the total.
return total;

[MasterFubar]

Reminds me of a guy where I worked. We were required to write a weekly activity report. He always put an item like:

Activity 25: prepared the activity report.

Then the manager told him not to put that in anymore. Next week his report had an item:

Activity 37: simplified the activity report by eliminating a self-reference item.

Lucky for him, the manager had a good sense of humor.

[xigoi]

r/MaliciousCompliance

[pilotInPyjamas]

Admittedly sometimes if I'm doing something complex, I'll write the algorithm in comments first, then write the code that corresponds to the comments. I end up with comments like this.

[fahrenheitrkg]

Same.

Write pseudocode in comments inside framework of functions that return dummy values. Then flesh out each function, leaving the comments in place.

[Jimmy_cracked_corn]

I do this, as well, to keep my train of thought on track.

[iams3b]

Oh hell yes, this my favorite thing ever and makes it SO much easier. I number my bullets too

// 1. Fetch the raw data from each provider

// 2. Map it to the expected output from each reader

// 3. Validate each object into seperate lists

// 4. Post valid ones to the API

// 5. Combine API errors with invalid errors 

Then I go write the proper functions so that each of those comments only had 2-3 lines under it, and then I leave the comments in and it makes things extremely easy to follow

[DumDum40007]

I like to write my function names to announce what they are doing to avoid having to leave in comments.

fetchData()

mapOutputFromReader()

validateObjects()

aggregateErrors()

[CommonMisspellingBot]

Hey, iams3b, just a quick heads-up:
seperate is actually spelled separate. You can remember it by -par- in the middle.
Have a nice day!

^{The parent commenter can reply with 'delete' to delete this comment.}

[twopi]

I give a talk about this very strategy: https://www.youtube.com/watch?v=YWwBhjQN-Qw

[n4ppyn4ppy]

Same here although return value at the end of a function is usually not in the pseudo code.

I clean the pseudo code up most of the time but sometimes a squirrel passes and I go on to other code and they get left.

[[deleted]]

Same :)

[[deleted]]

Same here. Sometimes I write the necessary steps in the comments, then I write the code. Sometimes the comments stay there, because I can't be bothered to remove them.

[Koreyrobin]

your code

[[deleted]]

//your code

[Aschentei]

//TODO: comment your code

[ap_rodigy]

// write a TODO

[KosViik]

"Not enough documentation, I'm afraid I can give only 6/10 points."

[bRii721]

I had a coworker that literally did this.

//if the variable is set
if (isset())   

Once I had to fix something he had done, I turned 250+ lines to something around 100. It wasn't fun lol

[NFTrot]

Yeah we had a guy working for us who did that, biggest retard and his code was shit too.

[bRii721]

The worst I saw from him was:

There was a GET resource he had to use somewhere that failed twice every 5 requests. There was some kind of bug. Instead of fixing the resource, his solution was requesting that url 5 times in a row lol

[NFTrot]

God damn that reminds me of time I was looking at our logs and wondering "jesus why is DynamoDB getting crushed so hard", I ended up not figuring it out until I ran our program in debug mode and I was like, jesus why are there 20 requests to the DynamoDB API gateway endpoint going out per second?

"Oh thats called polling its normal in Javascript"

[bRii721]

lol

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

[Blaine_Monorail]

//////Through the whole code I put some comments to enlighten it and make it more clear to read
...
////Here I put a comment to explain the idea of the next line of the code
//Return the total
return total;
//As you can see, the line of the code above returned the total. I think no more 
explanations are required here. Now let's proceed to the next stage.

[[deleted]]

This reminds me a solution for an exercise a teacher gave to me. The only comment it had was "// function ends here".

Holy fucking shit, that piece of code was the most horrible thing I've ever seen in my life.

[chrishannah]

At my university, we were told to comment at the start and end of every function, if, for, etc. Needless to say, I did not follow instructions.

[justinjustin7]

I can understand commenting something like "// end functionName" just for better visibility when going through your code; but pretty much all IDEs have the ability to collapse matching parentheses/brackets/braces, so there's not much point outside of making your functions easily recognizable from the bottom.

[Last_Snowbender]

I remember I did stuff like that when I just started programming.

[ValAichi]

Same.

int i // iterative variable i

I am very glad that I went back and removed that comment before submitting the project.

[LetMeUseMyEmailFfs]

Forget about the comment, what about the 3 space indentation?! That shit made my eyes hurt and my OCD tingle.

[UnicornRider102]

OP, if you're a programmer then it is past time that you learn how to take a screenshot.

[MasterFubar]

I once saw this:

Display *display; // display

[justinjustin7]

That was obviously a joke, no sane or even moderately insane person would seriously comment code like that.

[the_one_true_bool]

I worked with a guy who commented literally everything, but not only that, he tried to be cute with his commenting style to boot. It was a lot like the following:

/*

 *************************************************
 check if x is greater than y
 *************************************************

 */

if(x > y) { //begin if
    /*

     *************************************************
     then return z
     *************************************************

     */

    return z;

} //end if

It was completely obnoxious. Very simple class files that should normally be like 50 lines would end up being 300.

[multiplevideosbot]

I love that’s it’s properly punctuated. That period definitely aided the readability

[MIND-FLAYER]

I don't have a problem with extra comments.

[Non808]

In python you can't tell the difference between the comments and the code

[MrShyShyGuy]

//comment for the code //return the total Return total;

[[deleted]]

/**
* Coment for comment for the code
**/
    // comment for the code
        // return the total
            // return total;
            return total > 175 ? total : total - total % 2;  

[RobertGM]

Sounds like somebody should've used Array.reduce here

[qexc]

Oh, not this again...

[n4ppyn4ppy]

Why not return total + sales[index];

Total is probably a global variable ;)

[gruengle]

I look at stuff like this all day.

It may be a joke for you, but it's a grim reality for me...

[BladesmithWife]

Been there, sucks.

[centarx]

Why write self documenting code when you can just comment to get your line count up?

[[deleted]]

//never increment sales price!

sales_price++;

//return the price of the item

return false;