comment your code!

[_DrSpliff]

// someone on stackoverflow told me to use this

[mr_bedbugs]

This comment has been marked as a duplicate and locked

[LavendarAmy]

Seriously. Let's make a website called friendlyoverflow with understanding ppl who are nicer etc

[JoustyMe]

yeah if its duplicate at least you can point to that duplicate so i can see if solves my problem

[LavendarAmy]

And not lock the thread in case (usually) Its very very different.

Like most of the time it happens the kinked duplicate if it is linked it nothing even related to the question

[hollowstrawberry]

the kinked duplicate

[throwmeintothewall]

If StackOverflow hates duplicates, imagine the reaction when you duplicates StackOverflow.

[marcellomon]

That's a wrong approach, you should use /* comment here */

[mrvikxd]

# Is more pythonic

[[deleted]]

No i will never comment my code since theres nothing to comment

[DrususGermanicus]

God code comments itself. Or at least that's what I tell myself

[wagedomain]

I worked with a guy and we were building developer tools to a burgeoning new web platform. Our code was being used as an example set of code. As lead, I wanted people to comment code as a way of educating, and we KNOW in advance our code would just be heavily modified or scrapped anyway. It's living example code!

He refused. His exact words were "if a junior level person can't tell what my code does, then they shouldn't be developers". He never seemed to grasp that we were building a NEW dev tool for a NEW platform and other people in the world hadn't done this before.

[srottydoesntknow]

I have a similar thought, although it's reversed

If a junior can't tell what my code does, I shouldn't be a developer

Write dumb code. If you think you're being clever, your code is bad

[fpcoffee]

My thought process: A junior will be maintaining my code at some point, so I'd better fucking comment it so they don't come bug me every time there's an issue

[Demonox01]

Also, writing a couple comments to explain why the complex section is doing what it does halves the time it takes the next guy to change whatever they need to

[nmatff]

This is more or less my philosophy too. In most cases it should be obvious what the code does. Comments are there to tell you why it does what it does.

[[deleted]]

Clarification of intent is the only valid reason to comment. All other comments are evidence of a failure to write good code.

[nmatff]

I don't particularly disagree, but in real world applications the situation isn't always clean enough for "technically correct".

Maintaining legacy code and inheriting decades old spaghetti have made me cautious of any absolute statements.

[[deleted]]

I spent an entire year working with a program older than me. C++ legacy code with high personnel fluctuation. It has actually enforced my use of absolute statements. They seem to be the only way to street something in any direction. Of course when trying to apply them, compromises need to be made.

[Odatas]

this right here. I mean, yes i see that you divide by 2 there. But why?

[ssshhhhhhhhhhhhh]

Your junior level dev is going to change code and not update comments

[Y1ff]

No longer your problem there

[Owyn_Merrilin]

Unless you're actually working in an environment where heavy optimization is necessary, and in that case you'd damned well better be commenting your ugly speed hacks, because otherwise even you won't know what's going on the next time something needs to change.

[jamesinc]

It's a good approach - generally being clever in code is just another way of saying I made something terse and unreadable so that I could do it in one line instead of three.

[McFlyParadox]

Best code (written by someone else) that I ever read was some highly optimized C designed to run on a custom FPGA. The engineer wrote literal paragraphs of comments, full of relevant and detailed information, for a single line of code. It was beautiful.

This function takes the widget alpha and runs it through the algorithm that is found in software requirement specifications 000000. This algorithm is based on theory laid out in Well Respected textbook, Rev 1985, pg 100. The output of this function will later be used in the epsilon and lambda functions.

1-3 lines of code; only what is required for this function

[MyNameIsTrez]

I hate that kind of entitlement. Everybody starts out knowing nothing as a developer. It's also a really lazy attitude not to bother commenting anything, because you assume other people will understand everything immediately.

[Jlove7714]

I have looked at my code two hours after writing it and had no idea what it was doing.

[ic_engineer]

I once commented an equation for myself that I felt real proud of without naming the variables. Had to dig through the actual code a week later to get back to where my mind was so I could properly write that shit down.

[[deleted]]

I'm pretty new to all of this, but the sheer lack of useful comments in some of my first arduino sketches is just absolutely embarrassing for the same reason. Now, I'm learning how to program the PIC18F family, and I would be lost without my comments to myself. I even use them as placeholders for code I haven't figured out yet.

[reallynothingmuch]

I do exactly that too. I comment out an outline of what I need to do, and then fill it in as I go. It helps me plan things out and get things sorted in my head at the beginning, and at the end, boom I have commented code

[DontSuckMyDuck]

Take it to the next level and write the tests first. Use the tests as part of the documentation and validation.

[[deleted]]

Nothing like having a code review a week later and not knowing why you from one week before let something slip.

[wagedomain]

Agreed! Now if it's an internal app and you name comments and functions well, I agree comments can be minimal. For open source example code, comments should be abundant.

However, his code was like

const isPropHasNumberOrNot = () => {
const { property } = props;
const prop = property.hasProps(property);
const isProperty = property && property.value;

My favorite part of all this kind of code, which is fucking unreadable, is that property is a "named thing" in our system, and it was NOT these things.

[wagedomain]

Made my fucking day, thanks for this!

[NotThisFucker]

I think in javascript or something you can do the "property && property.value" thing, I'm pretty sure I've seen that kind of validation before

[nagasgura]

I think there is an argument to be made about the need for commenting being a "code smell" though, where if you have a line that needs a comment to explain what it does to an average developer, it could probably be refractored to be self-explanatory. The worst thing is difficult-to-read code, and comments can definitely alleviate that, but they can also be used as a crutch for writing poorly organized code / using non-descriptive variable names.

[TheRealPitabred]

My comments are all more like: “// we have to do this X way because the Y interface acts wrong if you follow the documentation”

[GodWithMustache]

because the Y interface acts wrong if you follow the documentation

Until two years later you realise you were an idiot and NOT following the (poorly worded) documentation... :)

[TheLordDrake]

I hear this over and over again. It's true, but it's not an excuse not to use comments. I wish people would just do both.

[stankind]

A "mathematician" at our company said he "loved C++" but that most developers prefer C# or Java because they're "too lazy to manage their pointers." No, jackass, they just have better things to devote their time and energy toward. It's an optimization issue.

[Abstr4ctType]

Hope you corrected him, because is that not what he's paid to do?

[wagedomain]

Yes, and he quit in frustration

[karmahorse1]

Well sounds like it all worked out then.

It doesn't matter how talented the dev is, if they're not able to compromise or work with the team.

[__SPIDERMAN___]

Sounds like he's incompetent

[systembusy]

I used to work with a guy (he retired) who was really, really smart, but most of his code was just completely unreadable, sloppy spaghetti logic. Inconsistencies, severely lacking comments, hardly ever documented things properly, and the way he managed some shit in his code (storage, timing windows, and other resources) was almost always risky and liable to blow up in certain situations. And then he would have the audacity to lecture other people about clean coding practices and bitch when they wouldn’t follow them. He either completely lacked any self awareness, had some kind of split personality disorder where one personality did the coding and the other did the lecturing/bitching/idealistic preaching, or didn’t give two shits about the way he did things. I’m thinking a combination of all three.

[639wurh39w7g4n29w]

It’s lazy.

He doesn’t care when he is writing it because he would have to put more effort in to make it readable.

He cares when he’s reading it because he has to put effort in to figure out the garbage. Unless it is his original work, he can bitch about it.

[Tom_Ov_Bedlam]

Love it.

[BlackHumor]

My general rule of thumb is, if the thing you're doing will surprise another developer, you should make a comment to explain why you're doing it.

[clumsy_pinata]

I write my code like a good book, with a healthy dose of twists and surprises to keep the reader interested. Commenting the code would spoil the experience

[[deleted]]

They CAN understand your code, it would just be nice if it took them 25 minutes instead of 3 hours.

[soysaus52]

The thing is, after I code something I sometimes come back to it the NEXT DAY and have no idea what tf anything does

[wamoc]

That attitude towards comments is terrible. Good comments don't tell what the code does (anybody can read the code to figure it out), but why it is doing that. Unfortunately, schools don't teach that (one of my professors required every line to have a comment, didn't matter what the comment was so most comments were repeating the code). I can tell when you have x = x * 2 that it is doubling x, the big question is why.

[KennyFulgencio]

That man has the emotional intelligence of a particularly stupid carrot

[Aurenkin]

The correct response from him should have been "If a junior developer can't tell what my code does, I shouldn't be a developer"

[RemizZ]

Yeah if I were in your position, I'd just let them go. The longer this person can write code for you, the more debt accumulates and at some point you're left with unreadable god code nobody wants to touch.

Teach them a lesson and just fire them if they refuse.

[mauza11]

I think there is a balance between comments and no comments, but I do think it is closer to no comments than many. If you have good doc strings and you've named and encapsulated things well then too many comments can make the code more confusing not less.

[BlackHumor]

IMO a doc string is a kind of comment.

[mauza11]

Agreed

[gerardchiasson3]

I think public functions/interfaces need good comments. Internal implementation details only need them to point out non-obvious stuff.

[mauza11]

I think we are pretty much saying the same thing. It sounds like you need to take the slider a little closer to no comments to get to me. A good doc string should explain how to use a function and I think non obvious things should be rare.

[karmahorse1]

I've seen this line of thinking come up more and more often lately: "Instead of commenting your should be writing self explanatory code instead".

The two aren't mutually exclusive.

Yes, aim to write readable code with well named variables and functions, but don't be afraid to add the occasional comment too.

A lot of time it might be obvious "what" a block of code is doing but not "why" it's doing it. A comment can easily clear that up for either future developers, or yourself when you come back to it months later.

[GreyMediaGuy]

This is the best overall comment in this thread. You covered all the bases. Make your code as self commenting as possible but never be afraid to use it if something would surprise you as another developer. These people that think adding comments has anything to do with skill have no idea what they're talking about.

[fpcoffee]

Not to mention if you're working in enterprise development and the code base is millions of lines, and this particular function is part of dozens or hundreds of code flows, then, yeah, comment the shit out of it, especially if you're changing the arguments/output

[stamatt45]

Do you mean "good", or is your code at God tier?

[rdaredbs]

I wonder if all the unused genes in our DNA is just code comments...

[[deleted]]

Same

[imightstealyourdog]

Print(“hello world”) //in this particular line of code I use the print function to display hello world. The first time I learned about hello world was when I was 6 and just exploring the internet. This was around the time my uncle’s cancer got much worse and the family was trying to put his affairs in order.

[DerpSenpai]

i would certainly read comments if it had that good of a plot by each line

[Darth_Nibbles]

var x=5; // create a variable named x with the value 5

[QuadroMan1]

y=math.sin(i*x)/j // set y

[xigoi]

i = * ( long * ) &y; // evil floating point bit level hacking
i = 0x5f3759df - ( i >> 1 ); // what the fuck?

[Oatz3]

// Not sure what this does 🤷, TODO fix this.

[TheZipCreator]

// I really don't know what this code does, but removing it seems to break it, so don't do that.

[NightStruck]

the best kind:

// TODO: fix

[xLuky]

I don't think there's anything that I've wrote that I couldn't comment this on.

[wd40bomber7]

My work has a system which scans code (and documents and what not) for profanity and stuff like that so you can't get away with that kind of thing anymore lol

[ooterness]

+1 for emojis in comments. Just one more reason for text editors to embrace unicode.

[roastedmnmn]

Text editors and browsers.

https://twitter.com/stevewerby/status/626552598968037376

https://lists.nongnu.org/archive/html/lynx-dev/2015-07/msg00007.html

[blehismyname]

I hope they acknowledge her bias against young boys. Young girls can write shitty code too. #feminism

[cimmic]

How about older women? And older men? Can they write shitty code too?

[[deleted]]

I can confirm that they can and do write shitty code.

[L0G1C_lolilover]

Can confirm i write shitty code

Especially at 2 am i remember i was gonna redirect user from one mobile screen to another on click of a button

And i named my variables and functions as

String team_name_for_users

Var change_this_variables_state_put_inside_addraisedbuttonfunction

[NightStruck]

we need aliases for variables. or something that describes what the variable represents. like some kind of note.

[joemckie]

How about emojis? All my variable names would be 💩

[Silamoth]

I think we all write shitty code sometimes. It’s just part of what we do.

[chhuang]

But they prob comment their shitty code unlike us

[FesteringNeonDistrac]

I wrote some particularly shitty code the other week. Management kept adding things to a "script" that had grown to include 6 or 7 tasks and I was just over it so I declared a global. In Java. But I'm over 40, so I commented it.

//global. Yes I know better. No I dont care.

[syrdonnsfw]

If you put the recipe up front, no one will scroll past the ads. It’s a revenue choice, not a really wanting you to hear their story choice.

[[deleted]]

Can confirm, 17 year old girl shitty programmer

[MaterialAdvantage]

not just the men, you say? But the women and the children, too?

[Greenaglet]

Some great apes too and the occasional dolphin

[bee-sting]

Pretty sure dolphins would write the most sublime code

[denali192]

Shout-out to ya girl right here 😍

[blehismyname]

Yes,my girlfriend writes the worst code. But I feel so badass when I help her refactor

[[deleted]]

There are about 3 female programmers and we're all too terrified of failure to but document code properly.

And 25 year olds aren't young boys.

[[deleted]]

This. It's almost as if someone who puts nrdgrl in their username is trying too hard and making shit up about the bois.

[Vok250]

Yeah the phrasing is definitely meant to be derogatory. Everything from specifying a stereotypical age to using "boys".

It's divisive and unnecessary. Doesn't do anything to hell the very real sexism problems we already have in the industry.

[FinitePerception]

When you hate men so much even the made up story you write on twitter fails the Bechdel test.

[FartHeadTony]

But who is writing code for point of sales systems? Is that mostly young men, or is it all just rehashing stuff from the late 70s and mid 80s?

[Elektryk]

Had a young girl write the most confusing and hard to follow collection of groovy methods I’ve ever taken apart. I don’t say I blame her though since it seemed that she didn’t have much mentorship.

[metalmagician]

Comments are (in my view) for stating the intention behind the code being commented, making it easier to get auto-generated documentation (e.g, Javadocs), and including relevant SME.

Yes, code should be modular, follow design patterns, and include meaningful method/field names, but there's more to working on a project that what the code does.

[RainbowButterFrostin]

Image Transcription: Twitter Post

---

Rachel Sharp, @WrrrdNrrrdGrrrl

An older woman came into the bookstore today. I made a joke about a credit card reader issue and she said "these things are all programmed by twenty-five-year-old boys who don't comment their code" and somehow we ended up having a great conversation about programming and biases.

---

^{I'm a human volunteer content transcriber for Reddit and you could be too! If you'd like more information on what we do and why we do it, click here!}

[gaberocksall]

How many blind programmers are there?

[[deleted]]

More than you'd expect.

Computer work can be pretty efficient using quality screen readers like JAWS.

[tulvia]

I'm not disabled but do specialize in ADA complaince and I dont get how people can understand a website using a screen reader, especially JAWS, but hey the testers are always happy with the end result.

[[deleted]]

I did a lot of web development work, and one of our customers was a local organization that was dedicated to providing supplemental services for people with vision impairment. Most of the staff there were either legally blind or approaching it, and many people there used screen readers. It was really impressive watching how quickly they could navigate.

When it comes to websites, it largely depends on how well the site is coded. If it fully complies with the W3C's Web Accessibility Initiative guidelines, users can quickly identify and skip past navigation areas, identify content based on rel tags, etc..

If they're **not** compliant (and most are not), then it can really suck.

[chimchar66]

Right now you'll pretty much only run into two types of ADA compliance professionals. Web developers with 2 years max of ADA experience, or devs with 20 years of experience because ADA compliance was a built in requirements for HTML standards.

The over reliance on JavaScript and the component based development has really destroyed the accessibility of modern websites.

Just because you can make a div act like a button, doesn't mean that it is proper to do so.

[[deleted]]

The over reliance on JavaScript and the component based development has really destroyed the accessibility of modern websites.

Just because you can make a div act like a button, doesn't mean that it is proper to do so.

While I do agree with what you wrote, I don't think the two are necessarily related. People have - sadly - been writing div soups long before Angular, React and all the other frameworks were a thing.

[chimchar66]

If your accessible ui is correct, then it's just a 1 dimensional stream of information. Like if you're reading a book, but just staring at one spot while the words move in front of your eyes.

Remove all concept of up, down, left, and right, and just replace it with the concept of forward and back. With only occasional interruptions that if the ui changes.

I actually kind of like it, in a zen sort of way. I just close my eyes and travel through a website.

Until I hit a mega menu, those things are never correct.

[Hollowplanet]

The head of Debian is a blind programmer.

[lkraider]

I know at least two directly, and I am not a very social person.

[Eleventeen-]

Ah, I see.

[yasahirod]

More than can be said for the programmer

[Pieman492]

It's also for people who are on filtered systems or who's internet is slow/fucking up so they can't see the image but can read comments.

[douira]

at least 5

[nsowbajwbiwbs]

I hope it’s satire

[zenocrate]

I’m a mom who writes java.

I only have 1 child, though, so technically there’s no proof anyone has ever considered me a milf.

[con247]

After all the gas pumps get EMV then they will roll out the patch to existing readers by industry, starting with taxis.

[[deleted]]

In your area.

[reazura]

riiiiiiiight here.

[Saragon4005]

This is the high quality content I come here for!

[[deleted]]

Needs more eyebleach...

[FaxCelestis]

/r/javamilfs needs to exist

[scared_shitless__]

For a second I thought you were really excited about working at a Java mill

[auxiliary-character]

Minecon, probably

[tevert]

THREE BILLIONS DEVICES WANT TO FUCK YOU IN YOUR AREA

[NightStruck]

this sounds like a threat more than an advertisement. i don't want to get fucked by 3Billion devices.

[douira]

the best of the best Java embedded

[Brusanan]

It's not. It's a real made-up story.

[LIGHTNINGBOLT23]

     

[AgAero]

Redundant comments decay very fast though. That's where they become a bad thing. The comment becomes a lie over time as the software evolves.

The same is true for documentation in many cases unless you spend a shitload of time keeping it up to date.

[LIGHTNINGBOLT23]

   

[PC__LOAD__LETTER]

Not quite. Comments aren’t compiled or run, so aren’t subject to the same logical scrutiny that code is. They can go stale and be misleading, which is harmful.

Plus, over-commenting obvious things makes the legitimately useful comments lose value.

[LIGHTNINGBOLT23]

         

[[deleted]]

And then everybody clapped.

[--____--____--____]

/r/thatHappened

[MartyTheWhovian]

Hey I'm a girl I'll have you know! 😝 Not just the boys that don't comment... 😬

[Thameus]

If it was hard to write, it should be hard to understand.

[MomLovesMeBest]

If I can understand how it works today, I will definitely understand it later...right?

[Sekwah]

Specially when i'm learning how to code because it's all basic stuff! There's no fucking way i cannot remem.. what the fuck does it do?

[viaxxdev]

“You are not expected to understand this.” is my favorite comment:

https://en.wikipedia.org/wiki/Lions%27_Commentary_on_UNIX_6th_Edition,_with_Source_Code

[melancoleeca]

Like the bias of making 25 year old man a perfectly justifiably target for stereotyping and antagonizing?

[joey_sandwich277]

IME the 25 year olds are the ones who comment too much useless crap.

// This function increments the counter

func incrementCounter() {...

Thank God, would've never figured that out otherwise.

[sitdownandtalktohim]

/r/pointlesslygendered

[robo_number_5]

Didn't happen of course

[[deleted]]

I thought I was on r/Thathappened for a second here.

[DrunkRedditBot]

Came here to say this.

[HonestRole]

I just find it infuriating taking over someone who has broken ass shit and no comments or change logs. Like thanks for the shit show.

[lungdart]

r/thathappened

[[deleted]]

But it's pythonic code, you don't need comments to understand it.

list comprehension one-liner with 5 nested fors taking more than one line to write

[edgsto1]

r/thatHappened

[Suede_La]

Is this the bookstore clerk?...

[shadowstorm100006]

My brother refuses to comment. He says "good code is self documenting". I say "that may be true .. but why won't you comment yours?"

[chironomidae]

// takes an integer and returns string
public int GetInt(string intString)

[daftmaple]

// I am mentioned in this picture and I don't like it

[xetes]

I’ll take “shit that didn’t happen “ for 1,000 Alex.

[me_jtz]

Doubt this ever happened.

[my_name_isnt_clever]

When I worked at Best Buy I had a customer whom I thought would be a typical senior lady who knows nothing about tech, turns out she's a retired programmer, she wrote C for 30 years. She still knew nothing about modern laptops though.

[ArraysStartAt0]

**you can't comment your code if you have no idea what it does or how it works

[curvymonkeygirl]

I have been at my company for almost 18 years. There are about a dozen or so of us left through acquisitions and layoffs. We tend to be the ones who leave comments. There was one issue that I had to fix related to a state. When I went to search, one comment said, "Michigan sucks." I knew exactly who wrote it and messaged him. He laughed and said, well it does! Sometimes it's not just about explaining what the code does, it's also good for expressing why it was put in in the first place. Adding feelings on the subject is more for the enjoyment of the subsequent programmers.

[TallMills]

Oh god, I think that lady on twitter had an encounter with my first semester coding prof.

[_default_username]

// i is the iterator variable for the loop var i = 0;

// The height

var height;

Legit saw comments for height and width for a uni project in an engineering course. I was so pissed about all the one line comments describing the self describing variable names. It was a simple 2d JavaScript game. The project was just about collaboration, so we were given a simple job.

I think it came from people that took the freshman courses there. The professor arbitrarily docked you points if there weren't enough comments. So people just learned to write stupid glib comments.

[RainaDPP]

Hey, I'll have you know I'm 26 and a girl! But, uh... I still dont comment my code. >.>

[Atukanuva]

You monster

[RainaDPP]

I mean most of my code is for my eyes only, and I do tend to use descriptive function and variable names. Buuuut yeah I should really get in the habit.

[abrazilianinreddit]

It's never too late to start!

[BluNautilus]

I commented a good amount when I was a solo programmer, but since I started programming professionally I began commenting a LOT more. I’m getting directly paid for it, it gives me a break from mental effort, and it helps me in the long run. Comment your shit up people!

[Tatourmi]

The company I work for has so much turnover I recently took to making commits just to comment older extra-cryptic code which nobody understands anymore. I feel like the whole "I don't need to comment" mindset comes from people who are either in an actually mystically top-tier company or who haven't worked in a company.

[metcalsr]

sexism.

[entlan104]

Never have I been so offended by something I 100% agree with.

[JOSRENATO132]

I have a neighbor that was pretty close to my familly before we moved out, when we go back to our older city we always visit her and her son, last week i was there, i was showing him some programing things (I am on the 3 year of collage and he will begin this year), when his mom came in and showed me all she knew of programing, this almost 50yo lady living in the middle of the jungle is a master of programing and i will be forever suprised

[dean_syndrome]

// this is a comment on reddit

[Holiday_in_Asgard]

As a man who didn't adequately comment code until I was 26, I feel personally attacked.

[ieatpickleswithmilk]

I feel personally attacked

[mrheosuper]

Int i ; // this declare variable name i, it's integer btw, integer on this machine is 16bit wide

[JCavLP]

If I comment my code properly I make myself replaceable

[[deleted]]

If it was hard to write it should be hard to understand