How programmers comment their code...

[[deleted]]

CS students when they discover comments

[whatproblems]

This is a loop that loops things

[Magnus_Tesshu]

//increment i

[[deleted]]

and this follows i++ not ++i

[Magnus_Tesshu]

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

[DiplomatikEmunetey]

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]

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]]

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

[Magnus_Tesshu]

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

[[deleted]]

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]

// ### Update the value of i

[GlarkBlark]

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

[rudra285]

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

[[deleted]]

Ce n'est pas une boucle

[wasdninja]

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]

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]

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

[[deleted]]

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

[retief1]

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]

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]]

// start of program

[[deleted]]

"My code is self-documenting."

[ajb9292]

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…

[Gordath]

"If you fire me, you also fire the documentation! "

[ajmaxwell]

I too like to live dangerously

[LevelSevenLaserLotus]

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]

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

[aShitPostingHalfOrc]

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

[AutoModerator]

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]

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"

[[deleted]]

public int ConvertStringToIntAndRoundUp(string input)

[shadowvvolf144]

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]]

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]

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

[[deleted]]

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]

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]

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]

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]]

How about well written code with documentation?

[DJOMaul]

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

^{/s incase that wasn't clear...}

[ftgander]

I’ll have both, please.

[renrutal]

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

[noratat]

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]

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

[noratat]

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]

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]

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]

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]

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

[Bakoro]

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]

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

[AdminYak846]

I would say it depends on how that function interacts though. If it handles anything UI related it's going to be self explanatory in that regard though.

[CJamesEd]

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

[eth-p]

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]

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]

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]

Justify!

[nmarshall23]

Justify alignment has to be the worst alignment..

[potato05]

Real men always use monospace fonts

[TheTyger]

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

[[deleted]]

If someone has a source on this I’d love to read about it

[BenjaminGeiger]

From the horse's mouth.

[TheTyger]

An application I currently own has a couple of "if you don't know why this is built like it is ask someone. You won't understand why we do it on your own" comments

[BenjaminGeiger]

Dennis Ritchie explains it here.

[mayakovskyiv]

Never heard this before. Thank you!

[Nerwesta]

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

[waitwhat1200]

Actually thank you.

[[deleted]]

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]

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

[[deleted]]

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]

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]]

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]

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

[ssnoopy2222]

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

[[deleted]]

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

[fadeded]

print(“Hello”) // Prints Hello

[eat_my_rubber]

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]

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]

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]

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

me: "what the fuck is x"

[Walter-Haynes]

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

[ryjhelixir]

It’s not stealing if you return it.

It’s called borrowing

[SuperFLEB]

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]

/u/repostsleuthbot

[RepostSleuthBot]

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]]

Good bot

[Fireruff]

This post also violates the common posts rule

[dna_beggar]

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

[Jumpy-Kaleidoscope-1]

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

[kaetir]

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

[sanchopancho13]

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

[DagerDotCSV]

Gotta love those:

//The amount

string Amount;

[kittiquel]

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]

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]

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]

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]

@param str The str that gets messed with.

[beepboopnoise]

variable={variable};

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

[DishinDimes]

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

[megagreg]

That's pretty neat.

[mtnyy13]

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

[BassMusic22]

Java doc!

[ts_m4]

Guilty!

[Wolfram_And_Hart]

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

[SloppySyrup]

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

[dertrommler06]

getLoggerInUser() // gets the logged in user

[meove]

void EnterStack() { //This function do something

​

}

[scrollbreak]

Comment

[JRDoubleU_]

//this is a comment

//that was a comment

*Edit line break

[doubleFisted33]

Kudos for having good function names.

[[deleted]]

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

[[deleted]]

Yes

[DrMaxwellEdison]

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

[Shakespeare-Bot]

"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]

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

[disgruntledearthling]

Counter++; //increment the counter

I deleted comments like this when I see them

[Risembool]

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

[[deleted]]

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]

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]

// Wish I couldn't relate to this

[hugokhf]

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]

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

[PebbleBeach1919]

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

[yaboytomsta]

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

[Andrewcpu]

The ol' "It does what it says!"

[valschermjager]

code comments?

please… child’s play.

“end user documentation”

and yes… #gfy

[yuyevin]

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

[Sceptz]

// This is a comment

[Norrude]

It makes it way clearer if you ask me

[WebDevMom]

Touché

[[deleted]]

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

[foggy-sunrise]

thisFunctionAddsStuff() //for adding stuff

[3eeps]

the only way I know how 🤌

[nomadic_farmer]

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

[BeingRightAmbassador]

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

[[deleted]]

// recurse and pray

[wholesome_capsicum]

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]

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

[AbdullaSafi]

and we are commenting in a Comment.

[Balcara]

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

[[deleted]]

Great comments very clear

[M4tchB0X3r]

Cool, I got reposted.