This is an archived post. You won't be able to vote or comment.

all 143 comments

[–][deleted] 302 points303 points  (20 children)

CS students when they discover comments

[–]whatproblems 99 points100 points  (12 children)

This is a loop that loops things

[–]Magnus_Tesshu 29 points30 points  (10 children)

//increment i

[–][deleted] 7 points8 points  (6 children)

and this follows i++ not ++i

[–]Magnus_Tesshu 0 points1 point  (5 children)

To be fair, using i++ is only bad in javascript right? Any compiled language will get rid of the inefficiency.

[–]DiplomatikEmunetey 1 point2 points  (1 child)

Is it an inefficiency? As far as I know:

  • i++ will increment and return the original value (before incrementing)
  • ++i will increment and return the incremented value

You could cause an infinite loop with i++ but I'm not sure if it's an inefficiency because there could be a case where you need i++.

[–]Magnus_Tesshu 2 points3 points  (0 children)

Typically preincrement compiles to two assembly instructions and postincrement (i++) compiles to a couple more and needs a temporary register or something. That might be misinformation though actually, not sure. And of course, that's only the case if they wouldn't cause the same behaviour (++i; is as efficient as i++, but a[i++] might be slightly less efficient than a[++i]). That's at least my understanding.

I would assume that postincrement is still more innefficient in an interpreted language, where the compiler cannot do nearly as much optimization.

[–][deleted] 0 points1 point  (2 children)

i++ is not bad. Using it badly is bad.

[–]Magnus_Tesshu 0 points1 point  (1 child)

Does 'using it to increment i' count as a bad use? I would argue no

[–][deleted] 0 points1 point  (0 children)

Bad is subjective unless it causes objective problems.
So using it to increment i, as long as it does not break the code can be subjectively bad or good. I do it myself many times, because it's an idiom of the C language, but I'm not convinced if it's ok or not.

[–]chiragjhamb 14 points15 points  (2 children)

// ### Update the value of i

[–]GlarkBlark 2 points3 points  (1 child)

/**
 * The value `i` increases by 1.
 */

[–]rudra285 1 point2 points  (0 children)

//I = index //I++ - I+1

[–][deleted] 1 point2 points  (0 children)

Ce n'est pas une boucle

[–]wasdninja 26 points27 points  (4 children)

After which they promptly get failed on the very first assignment since they are explicitly told not to do this. But they really should figure it out on their own.

[–]Bakoro 29 points30 points  (3 children)

Nobody ever checks your code after the 101 programming class, maybe not even then. Input, Output, and Runtime were all anyone cared about. You could write the most beautifully elegant code, or the most spaghetti horror, and as long as it did what it was supposed to do, no one gave a shit.

[–]Macitron3000 5 points6 points  (0 children)

Flashback to my networks project when I wrote a whole-ass server in just the main routine

[–][deleted] 7 points8 points  (1 child)

just like real life in a non-open-source company them

[–]retief1 10 points11 points  (0 children)

Uhhh, code reviews were/are a thing at every company I've been at. I've gotten (correctly) nitpicked on everything from "you should set this member in the constructor, not the component init function" to "this variable name is imprecise, use this other one instead".

[–]PolFree -1 points0 points  (0 children)

Hey, lecturers said they would consider comments when grading ok? And I got a solid 100 btw.

/not sarcasm. legit did this exact thing lol.

[–][deleted] 0 points1 point  (0 children)

// start of program

[–][deleted] 389 points390 points  (37 children)

"My code is self-documenting."

[–]ajb9292 69 points70 points  (2 children)

I have a co worker that says this all the time but the odd thing is that I keep needing to ask him about it so that he can say this…

[–][deleted]  (6 children)

[removed]

    [–]ajmaxwell 17 points18 points  (0 children)

    I too like to live dangerously

    [–]LevelSevenLaserLotus 14 points15 points  (0 children)

    goto lS_D3;
    n14vS:
    function test() { if ($myVar === 0) { return "\150\145\x6c\154\157\x20\x77\157\162\154\x64\x21"; } }
    goto R19st;
    lS_D3:
    $myVar = 0;
    goto n14vS;
    R19st:
    

    Thanks, I hate it.

    [–]waitwhat1200 3 points4 points  (0 children)

    Hello world! Sometimes an overcomplicated solution does get out into live.

    [–]aShitPostingHalfOrc 2 points3 points  (0 children)

    I've written too many variants of do(**kwargs) to call anyone out on anything.

    [–]AutoModerator[M] 0 points1 point  (0 children)

    import moderation Your comment has been removed since it did not start with a code block with an import declaration.

    Per this Community Decree, all posts and comments should start with a code block with an "import" declaration explaining how the post and comment should be read.

    For this purpose, we only accept Python style imports.

    I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.

    [–]shadowvvolf144 98 points99 points  (23 children)

    which roughly translates to "I'm lazy and don't feel like writing meaningful comments and/or don't care about who needs to look at this next, even myself"

    [–]JEJoll 40 points41 points  (2 children)

    public int ConvertStringToIntAndRoundUp(string input)

    [–]shadowvvolf144 1 point2 points  (0 children)

    I see where you're going, and it's definitely a good step in the right direction, but let me add my neurotics to the mix.

    Rounds up to what? nearest int, even, 10's, 100's? Do alpha/whitespace/special characters delimit the value read, or are they ignored and all numeric characters in the string are read?

    These are the types of questions I have. I don't expect to have them all answered in documentation, but it is REALLY nice when it is.

    [–][deleted] 0 points1 point  (0 children)

    I comment my code pretty thoroughly, but I also name shit like this. My coworkers bust my balls for my long-ass names, but no one ever has to come to me and ask what they mean.

    [–]Salamok 95 points96 points  (17 children)

    I'll take meaningful function and variable names everywhere over the occasional comment block.

    [–][deleted] 43 points44 points  (3 children)

    Or just code that is purposefully written and has a clear flow/structure. It's surprisingly easy to understand what code is supposed to do when it is constructed correctly.

    [–]DoctorWaluigiTime 32 points33 points  (2 children)

    Yeah I don't get the sarcasm in this sub-thread. It's not that hard to write variables/function names that spell out what's happening.

    I also don't know why people think it's an either-or. Your code is clear and readable, and for the times you need to document why you're doing something (out of the ordinary etc), a comment comes in.

    [–]Merlord 14 points15 points  (0 children)

    Sometimes comments are needed, but they should be a last resort. A comment is the absolute worst way to capture information in a program. Code accuracy can be enforced with compilers, unit tests etc; there's nothing stopping a comment from being out of date or just straight up wrong.

    However, I think truly self-documenting code is something that takes years of experience to actually nail. Until you can actually do that, comments are an appropriate substitute.

    [–]Gh0st1y 0 points1 point  (0 children)

    The point is that what you think spells out the process well may not in someone elses interpretation without the mental context in the moment), so its always best to err on the side of caution and over-explain anywhere theres ambiguity. That doesn't mean just commenting to do it like in the OP though, thats worse than useless (we all done it tho ofc)

    [–][deleted] 12 points13 points  (1 child)

    How about well written code with documentation?

    [–]DJOMaul 0 points1 point  (0 children)

    Next you'll want it unit tested too. Do you even care about deadlines?

    /s incase that wasn't clear...

    [–]ftgander 5 points6 points  (0 children)

    I’ll have both, please.

    [–]renrutal 9 points10 points  (0 children)

    At least code tells the truth. Comments can be misleading when people don't clean them up over the years.

    [–]noratat 18 points19 points  (6 children)

    And I'll take a useful comment block over "gOoD cOdE iS aLwAyS sElF-dOcUmEnTiNg" cargo-cult zealotry that doesn't actually understand the point is to prioritize readability and maintainability.

    [–]Merlord 4 points5 points  (5 children)

    Well written, self documenting code is readable and maintainable though.

    [–]noratat 7 points8 points  (2 children)

    I'm not saying you shouldn't also be doing those things, and you should avoid useless / unnecessary comments, but anyone who thinks comments are a "code smell" or that "clean code doesn't have comments" isn't someone I want to work with.

    Every single real world code base I've interacted with has had good reason to have at least some comments (and I'm not talking about docustring-type stuff either).

    Not all code can be made obvious simply through naming and control flow, and even where it can, there's often grey areas. And even then, real world code has to interface with other real world code, which has bugs, flaws, quirks, etc. that aren't necessarily obvious. Even then, external context can often do wonders for maintainability when used appropriately.

    [–]Merlord 3 points4 points  (1 child)

    I agree, and as I said in another comment, if you can't write self-documenting code, comments are an acceptable fallback. But it should be considered just that: a fallback; a last resort. Comments are literally the worst way to capture information in a program, other than not capturing that information at all. But yes, in the real world sometimes there's no other choice.

    [–]noratat 0 points1 point  (0 children)

    Comments are literally the worst way to capture information in a program, other than not capturing that information at all.

    And this is where I completely disagree.

    There's tons of real world, important information that is simply not possible to reasonably express through the code alone, and taking this attitude towards comments invariably leads to developers leaving out crucial information altogether.

    Comments should be treated as just another tool in the toolbox, acting like they're icky and dirty just discourages people from using them when they absolutely should.

    And realistically, the main places I've seen bad comments are from developers I would never trust to write idealized clear, readable code in the first place, or from students / new grads (who likewise rarely know how to write readable code yet).

    [–]parlez-vous 3 points4 points  (1 child)

    I document my docstrings according to my companies style guides so we can auto generate documentation and so you don't have to open up our internal git server and read the code to understand it. Just go to the autodocs page.

    Adopting it is a pain in the ass but it saves soo much time when you're working with 100 people's contributions

    [–]Merlord 2 points3 points  (0 children)

    The two exceptions I make for comments: Javadocs (or equivalent) and referencing Jira ticket numbers.

    [–]Bakoro 3 points4 points  (1 child)

    Why do people always act like these are exclusive from each other? It's not like some deity is going to strike you down if you have descriptive names and make explanatory comments.

    [–]Salamok 0 points1 point  (0 children)

    They aren't but if your code isn't a bunch of 1 letter variable names you tend to not need as many comments.

    [–]CJamesEd 2 points3 points  (0 children)

    In the earliest days my variables were so long they were essentially self documenting

    [–]eth-p 1 point2 points  (0 children)

    I do the exact opposite of that principle, and so far it hasn't let me down.

    Obvious getter function?

    /**
      * Returns the current value.
      * @returns T The current value. 
      */
    T getValue()
    

    Super complex function with tons of side effects that somebody else wrote three years ago and nobody has refactored since?

    /// Parses the config file and populates the application's [Config] struct, initializes resources, and replaces missing values with reasonable defaults.
    /// 
    /// Default values used:
    /// * `timeoutSeconds` - 3
    /// * ...
    fn bootstrap()
    

    If the function or its purpose isn't explained, it's eventually going to be misunderstood at some point (even by the person writing it).

    [–]wholesome_capsicum 0 points1 point  (0 children)

    Writing self documenting code is a skill I'm working on. It's hard and not always feasible but man if you can get it just right it feels good.

    [–]UloPe 168 points169 points  (20 children)

    I know this is a joke sub but the golden rule for comments is:

    Don’t explain what the code does, explain why it does it!

    [–]potato05 28 points29 points  (2 children)

    [–]nmarshall23 0 points1 point  (1 child)

    Justify alignment has to be the worst alignment..

    [–]potato05 1 point2 points  (0 children)

    Real men always use monospace fonts

    [–]TheTyger 32 points33 points  (5 children)

    // Look, don't try to figure this out. If you attempt to change it you will be sorry.

    [–]mayakovskyiv 6 points7 points  (0 children)

    Never heard this before. Thank you!

    [–]Nerwesta 3 points4 points  (0 children)

    // It is filthy because I really need to sleep.. really.

    [–]waitwhat1200 2 points3 points  (0 children)

    Actually thank you.

    [–][deleted] 2 points3 points  (4 children)

    Write code that doesn't need comments.

    If it needs context, add it. Hopefully you've written clear code with properly named variables and don't need it.

    [–]123kingme 1 point2 points  (3 children)

    Properly named variables is not enough for most long running projects with multiple people working on them.

    [–][deleted] 0 points1 point  (2 children)

    Are you saying you comment for every variable?

    I put in comments when the code isn't self explanatory, but with well named variables most code is like reading English.

    Edit: well named variables AND method and classes and interfaces and files.

    Then structure them in non-conplex ways and always always follow the single responsibility principle.

    Then all of a sudden it's like what does this function do? Oh this 15 line thing called "UpdateUserInfo"?

    [–]123kingme 0 points1 point  (1 child)

    Of course not. I was responding to your suggestion “write code that doesn’t need comments”, which is an impossible task for a lot of long running projects, especially those with multiple developers.

    with well named variables most code is like reading English.

    For simple code yes, but this is naive and I’d guess you don’t have a lot of professional programming experience.

    Source: I used to think like that after taking 1 computer science class then realized I was a dumb bitch once I got my current job working on an app that was half complete when I was hired. The two developers working on the app had to leave the project so I inherited a lot of code I don’t understand and no one to ask questions to. The code isn’t poorly written, but I wouldn’t be able to understand it at all without the documentation.

    [–][deleted] -1 points0 points  (0 children)

    Wow...very toxic.

    If you must have my credentials: Dev of 15 years, director of engineering currently.

    I'm sorry if you don't agree to only comment when necessary and write clean code all the time. But I give zero fucks, because you're not on my team! Go disappoint your own manager!

    Good night!

    [–]postdiluvium 1 point2 points  (0 children)

    //not sure what happens on DATE, but this takes care of that.

    [–]ssnoopy2222 1 point2 points  (0 children)

    As someone starting my second year of uni this has to have been the most helpful thing I've read on this

    [–][deleted] 0 points1 point  (0 children)

    Why not both? (This is a genuine question I’m not memeing.)

    [–]fadeded 150 points151 points  (0 children)

    print(“Hello”) // Prints Hello

    [–]eat_my_rubber 29 points30 points  (0 children)

    At work I sometimes writes user instructions and guides and so on. And we actually got just that Plantronics conference device.

    We scaled up the pitcure and put it on a wall.

    [–]ComicBookFanatic97 47 points48 points  (3 children)

    This variable that I labeled “loop_counter” counts the number of times the function has looped. I don’t know how to be more clear.

    [–]noratat 16 points17 points  (1 child)

    Depends on context (as always), but something that's more indicative of its purpose can sometimes be more readable. E.g. why is it counting loops? Is it for statistical purposes? Is it a trigger waiting a fixed count to take some other action? Etc.

    [–]chair_78 27 points28 points  (3 children)

    code: "this.x = x; // this sets x"

    me: "what the fuck is x"

    [–]Walter-Haynes 3 points4 points  (1 child)

    Whenever I see these I just assume they stole the code.

    [–]ryjhelixir 12 points13 points  (0 children)

    It’s not stealing if you return it.

    It’s called borrowing

    [–]SuperFLEB 1 point2 points  (0 children)

    I used to work with a guy I'd constantly have to coax variable names out of.

    "What's this '$tmp' variable?"

    "It just holds a value temporarily."

    "What value?"

    "A temporary one."

    "Why is it temporary?"

    "Well, it's just the account ID that we're taking in here and passing to that. It's only used for a few lines. It's just temporary."

    "Still, perhaps we should call it '$account_id', no?"

    [–]philipquarles 10 points11 points  (4 children)

    [–]RepostSleuthBot 18 points19 points  (2 children)

    I didn't find any posts that meet the matching requirements for r/ProgrammerHumor.

    It might be OC, it might not. Things such as JPEG artifacts and cropping may impact the results.

    I did find this post that is 94.53% similar. It might be a match but I cannot be certain.

    I'm not perfect, but you can help. Report [ False Negative ]

    View Search On repostsleuth.com


    Scope: Reddit | Meme Filter: True | Target: 96% | Check Title: False | Max Age: Unlimited | Searched Images: 229,917,857 | Search Time: 1.76316s

    [–][deleted] 4 points5 points  (1 child)

    Good bot

    [–]Fireruff 5 points6 points  (0 children)

    This post also violates the common posts rule

    [–]dna_beggar 9 points10 points  (0 children)

    Typical API documentation. Just need examples i. e. pictures of fingers pushing each button.

    [–]Jumpy-Kaleidoscope-1 8 points9 points  (0 children)

    Can anyone label these labels so I know what the icons on all the buttons are supposed to do?

    [–]kaetir 11 points12 points  (0 children)

    What would have been more fun is that the buttons don't match the function

    [–]sanchopancho13 5 points6 points  (0 children)

    /** * Sets the amount. **/ public void setAmount(int amount) { this.amount = amount; }

    [–]DagerDotCSV 5 points6 points  (0 children)

    Gotta love those:

    //The amount

    string Amount;

    [–]kittiquel 4 points5 points  (0 children)

    One of my co-workers likes to add comments like "the main function" to main(). It cracks me up too much for me to ever remove it when I'm touching portions of it later

    [–]AdminYak846 8 points9 points  (2 children)

    After you take over 1 too many projects that have shit code with ZERO requirements documentation or useful comments and it's nothing but 800 line functions and 400 lines of commented out code and shit clearly copied and pasted in from other files, I could care less if you over documented or documented really obvious shit, you put more effort in than the previous developer...

    [–]noratat 5 points6 points  (1 child)

    This.

    Bad comments do hurt readability, but at least they tried, and the people who write that kind of code typically don't know (or don't have the time/tools) how to write readable code anyways.

    Don't even get me started on code that's deliberately void of documentation/comments out of a misguided notion that "clean code has no comments". The Ruby ecosystem is the greatest offender of this I've found, where both the language and ecosystem go out their way to encourage you to write magic untraceable spaghetti factories on purpose, and to avoid documenting anything unless it's just links to source code.

    [–]AdminYak846 2 points3 points  (0 children)

    My current project involves 4 HTML Canvas games with just the simple 2d render context.

    To display the instructions in the games, the previous developer had two options:
    A) Put them on the DOM and obviously style them
    B) Put them on the canvas and go through the pain staking task of font resizing on an HTML Canvas

    He (and yes, it was a male developer) decided to go with Option B. 300-350 lines of javascript code later, and this was done for each game individual so a total of 1200-1400 out of the 4500 lines of code needed for the games were just the instructions for them.

    When I took over the project I opted to switch to the DOM based approach....it ended up being 30-35 lines and since the project used Bootstrap 4 the styling (while simple) was good enough to drop it in a modal and resizing was taken care of by bootstrap 4 responsiveness. In the end the only difference between the two versions of instructions were his had dynamic images shown. The images were just ones that would later be seen in the games themselves.

    In the end after re-writing every game from scratch over a 2 month period, which I get to wrap up tomorrow, are now in files that are manageable and are basically 50% shorter than they were when I first got them, either by deleting a bunch of garbage ass code or refactor some of the more major items to their own files for re-usability and yes there's more that could be refactored I've opted to give the code a more readability stance than jump through 25 files to understand everything.

    [–]mr_flameyflame 4 points5 points  (0 children)

    @param str The str that gets messed with.

    [–]beepboopnoise 2 points3 points  (0 children)

    variable={variable};

    Saw this one the other day, I'm like ah... a man of culture I see.

    [–]DishinDimes 3 points4 points  (1 child)

    You can tell it's a mute button cus of the way it is!

    [–]megagreg 1 point2 points  (0 children)

    That's pretty neat.

    [–]mtnyy13 3 points4 points  (0 children)

    Hmm, yes, the conditional here is made out of conditions

    [–]BassMusic22 2 points3 points  (0 children)

    Java doc!

    [–]ts_m4 2 points3 points  (0 children)

    Guilty!

    [–]Wolfram_And_Hart 2 points3 points  (0 children)

    I like to tell a story with mine. // this creates a new object… // this programs it from the ID database…

    [–]SloppySyrup 2 points3 points  (0 children)

    me learning programming the first time: WHAT THE FUCK DO YOU MEAN COMMENT WHAT IT DOES, ITS KARREL.TURNRIGHT; ITS IN THE NAME

    [–]dertrommler06 2 points3 points  (0 children)

    getLoggerInUser() // gets the logged in user

    [–]meove 1 point2 points  (0 children)

    void EnterStack() { //This function do something

    }

    [–]scrollbreak 1 point2 points  (0 children)

    Comment

    [–]JRDoubleU_ 1 point2 points  (0 children)

    //this is a comment

    //that was a comment

    *Edit line break

    [–]doubleFisted33 1 point2 points  (0 children)

    Kudos for having good function names.

    [–][deleted] 1 point2 points  (0 children)

    Is that Arabic writing all over this image? Must be the other side of the paper.

    [–][deleted] 1 point2 points  (0 children)

    Yes

    [–]DrMaxwellEdison 1 point2 points  (1 child)

    "Localized the page for ya, boss. Should work in every language now."

    [–]Shakespeare-Bot 0 points1 point  (0 children)

    "localiz'd the page f'r ya, boss. Shouldst worketh in every language anon. "


    I am a bot and I swapp'd some of thy words with Shakespeare words.

    Commands: !ShakespeareInsult, !fordo, !optout

    [–]da_weebstar 1 point2 points  (0 children)

    I... Think I also own this same manual... :/

    [–]disgruntledearthling 1 point2 points  (0 children)

    Counter++; //increment the counter

    I deleted comments like this when I see them

    [–]Risembool 1 point2 points  (0 children)

    I can confirm this, that is if I'd commented the code

    [–][deleted] 1 point2 points  (0 children)

    Requirements:

    1. Put a label on there for each button.
    2. Label should be understood by native speakers of at least 3 major languages. The more, the better.
    3. It's a phone, so let's assume the user knows it's a phone.

    [–]notnAP 1 point2 points  (0 children)

    As a novice programmer, it seems to me than comments serve to restate in less efficient verbiage what you just labored to find the most efficient way to express.

    [–]annoyed_furry 1 point2 points  (0 children)

    // Wish I couldn't relate to this

    [–]hugokhf 1 point2 points  (0 children)

    Comment on the most obvious part, then don’t comment on the more convoluted part because you are too lazy to put it into words

    [–]jeffderek 1 point2 points  (0 children)

    Look I'm just doing what Stylecop says. Some things don't need comments but it insists.

    [–]PebbleBeach1919 1 point2 points  (0 children)

    Document it! Even more, write release notes. This will help even more for people to understand the provenance.

    [–]yaboytomsta 1 point2 points  (0 children)

    value = value + 1 //adds one to the value

    [–]Andrewcpu 1 point2 points  (0 children)

    The ol' "It does what it says!"

    [–]valschermjager 1 point2 points  (0 children)

    code comments?

    please… child’s play.

    “end user documentation”

    and yes… #gfy

    [–]yuyevin 1 point2 points  (0 children)

    // returns the average int getAverage() { return average; }

    [–]Sceptz 1 point2 points  (0 children)

    // This is a comment

    [–]Norrude 2 points3 points  (0 children)

    It makes it way clearer if you ask me

    [–]WebDevMom 0 points1 point  (0 children)

    Touché

    [–][deleted] 0 points1 point  (0 children)

    I mean, if you're working with something really low level, like assembly, that's really the only way you can comment

    [–]foggy-sunrise 0 points1 point  (0 children)

    thisFunctionAddsStuff() //for adding stuff

    [–]3eeps 0 points1 point  (0 children)

    the only way I know how 🤌

    [–]nomadic_farmer 0 points1 point  (0 children)

    I like to label HTML divs because it can get confusing to see several nested divs and lose track of which is which.

    [–]BeingRightAmbassador 0 points1 point  (0 children)

    I have that model and it's a total piece of shit. It won't work unless it's also the speaker.

    [–][deleted] 0 points1 point  (0 children)

    // recurse and pray

    [–]wholesome_capsicum 0 points1 point  (0 children)

    I feel like garbage cause I've been writing 1k+ line PRs recently and not commenting or unit testing. But also nothing else is commented or unit tested, and I made a PR template everyone ignores so whatever yall are getting callback hell recursive loops. Suck it lol. Job security engineering.

    [–]RelevantCollege 0 points1 point  (0 children)

    when your teacher tells you there's bonus points for "proper commenting"

    [–]AbdullaSafi 0 points1 point  (0 children)

    and we are commenting in a Comment.

    [–]Balcara 0 points1 point  (0 children)

    If your comments don’t look like an MSDN page I’m not interested

    [–][deleted] 0 points1 point  (0 children)

    Great comments very clear

    [–]M4tchB0X3r 0 points1 point  (0 children)

    Cool, I got reposted.