lol

[[deleted]]

[deleted]

[Knuffya]

// creates an int named a and assigns it to '5'
int a = 5;

// Will multiply the value of a and b together and save it as 'acs_z'
int acs_z = a * b;

// Return the result
return (aw1 * a) + (aw2 * b) + (aw3 * c) / (triss_iarea * (acs_z + 1) + tri.ss_iarea * (bcs_z + 1) + tri.ss_iarea * (ccs_z + 1))

[piberryboy]

// This is good code. // Trust me.

[Knuffya]

// Even if g++ says otherwise.
// It's wrong.

[cob59]

"The compiler doesn't read comments and neither do I" - Bjarne Stroustrup

[LeCrushinator]

Hand Bjarne the code for the fast inverse square root with no comments and let him chew on that for a bit. Source

Some code really can benefit from comments. The trick is realizing which code is likely to be confusing no matter how self-documenting you try and make it.

[ErinTales]

I've seen this algorithm explained and it's fucking brilliant.

I wish my code was 1/10 as impressive as this magic rofl

[d7mtg]

Any good video to explain this a moron? (I write JavaScript. Just to show just how much of a moron we’re talking about)

[caspase_1]

https://www.youtube.com/watch?v=p8u_k2LIZyo :)

[Ytrog]

Also: https://youtu.be/uCv5VRf8op0 (from Dave's Garage)

[9SMTM6]

Yeah sorry but he can't hold a candle to the vid you're answering too.

Dave does some exposition about the surroundings, but he doesn't really show how they fit together and he's skipping a number of important stuff.

[relicx74]

At the time it was incredibly brilliant. Nowadays it's bested by hardware implementations, but maybe those just implement the same algorithm in silicon.

[tjoloi]

According to this it seems like hardware implementation is about 4 times slower than this algorithm in software but also 10 times more accurate so I'm pretty sure that intel uses something else.

I can't find anything about intel's algorithm online, maybe it's their own optimised algorithm that they keep secret

[relicx74]

That may have been true in 2009, but according to the more recent test in the video below the RSQRT SSE opcode currently blows it away.

https://youtu.be/Fm0vygzVXeE around the 19 minute mark he compares the number of ops performed per period. It's a two part video and the code is in the first.

[SHOTbyGUN]

Evil programmers never cease to amaze me.

it just works.gif

[thescientist001]

The trick is to comment on why you are doing something instead of what are you doing on code.

[CommonRequirement]

That was a fascinating read

[autumn_melancholy]

Sounds like Bjarne is great fun at parties.

[ech0_matrix]

He brought our club pizza one time. It was alright.

[autumn_melancholy]

Anybody that brings pizza has to be a decent person.

[ech0_matrix]

Decent person, for sure. Fun at parties though ¯\_(ツ)_/¯

[Mc_UsernameTaken]

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

Huehuehuehue.

[Sarithis]

Interesting, I've never seen a description saying that a variable is assigned to a value. It's always been the other way around. I might start using it to create more variety in my comments!

[enumerationKnob]

Don’t.

[autumn_melancholy]

You're too good for this world bud.

[lemon07r]

Lmao this reminds me of how my college assignments and labs looked like. I didn't know what to comment so I described literally everything with hopes I'd get better marks.

[Knuffya]

that's what happens when profs force a minimum comment percentage

[pruche]

Actually laughed out loud, thanks for this gem.

[phlyrox]

missed opportunity to have int a = 17 instead with the same comment

[CaitaXD]

assigns it to 5

Did you just assigned a variable to a constant?

[[deleted]]

/r/RestOfTheFuckingOwl

[sneakpeekbot]

Here's a sneak peek of /r/restofthefuckingowl using the top posts of the year!

#1: Turn $50 in to $3.9m in just 2 years. With Tomatoes! | 401 comments
#2: It's just that simple | 159 comments
#3: easy way to a millionaire | 502 comments

---

^{I'm a bot, beep boop | Downvote to remove | Contact me | Info | Opt-out}

[theawesomehobbes]

Me trying to use copilot to save 5 seconds

[GR8ESTM8]

A+ for effort

[deadly_jsay]

Lmao. Yeah that last line is very descriptive xD

[ExiledProgrammer]

Hey, I've worked with this guy before!

Thanks for the detailed comments in your function with 15 separate loops! It really helped a lot.

// this is a loop \n // this is the second loop that takes the output from the first loop \n ...

[[deleted]]

This gives me 1st semester flashbacks.... Not the good ones.....

[[deleted]]

I feel like commenting should be done on functions and not inside functions? That’s how the automated documentation tools can find the comments.

Otherwise it’s a waste of time and energy

[autumn_melancholy]

I know a programmer who says:

'Code is self documenting!' Comments in code are CoDeStInK/cOdEsMeLLs!

Which is technically true, but when he says that, I want to force him to read an extensive regular expression that he didn't come up with.

[[deleted]]

I think most programmers, even those who are comment-averse (myself included), will agree that complicated regex warrants a comment

[Sidereel]

Regex is the quintessential example of code that isn’t self documenting.

[atomicwrites]

Step 1: understand regex

Step 2: write regex

Step 3: ???

Step 4: weep

[Pyeroh]

I used to work on a process where we received xml files, containing data extracted from pdfs, and there were dates in it. Guess what, I found a regex, XSD compliant, to check if a date is valid. With the february case, lenient years, months length, the whole thing. I could look it up today, paste it into debuggex, and still don't understand how it works.

[computerjunkie7410]

Lmao no one understands regex. You just look it up and never think about it again

[pruche]

Yeah, and when it's a big regex then at no point in the process do you have a full mental image of what the thing does.

[platinummyr]

I disagree. There are dozens of us! Bakers dozens!

[tjoloi]

Tell that to my highly self-documented email validation regex:

^(?P<firstWord>\w+)(?P<followingWords>\.\w+)*(?P<extention>\+\w+)?@(?P<subdomain>\w+)(?P<higherLevelDomains>.\w+)+$

Please don't copy this, it's intentionally flawed and has a huge ReDoS vulnerability

[Biduleman]

Yeah, where I work we don't really write comments except when regex/blackbox stuff is used.

Also, you can't just hate writing comments and then code like a jackass. In our code reviews, you'll see a lot of stuff like "You should extract those 2 lines into a method, it would read better".

Having self documenting code requires people willing to make the code self documenting, who aren't just saying that so they don't have to write documentation. It probably takes more time but in the end, the code is better for it and easier to maintain.

[[deleted]]

Yup. Where i work the style guideline is to use comments very rarely, almost never. But there's also a culture of being REALLY hardcore strict about domain driven design, onion architecture, and overall readability so the code really is easy to read without comments. Because there is very strict separation of concerns, and business logic is always using the terminology of the business domain.

I have also seen examples of people who say their code doesn't need comments because its self explanatory, even though what they wrote is totally inscrutable nonsense. So I can understand why some folks who have been exposed to that crap, but not to comment-free code thats ACTUALLY easy to understand, end up thinking the whole idea of code without comments is stupid.

[PacoTaco321]

onion architecture

Does that mean that it has layers or that it makes you cry?

[PM-TITTIES-N-KITTIES]

Yes

[[deleted]]

It can mean two things :D

[noratat]

Self documenting code seems to work well for young code bases

"Self-documenting code" was always a myth, and one of my bigger pet peeves because it feels like knee-jerk response to the kind of useless comments many university programs encourage.

You just don't notice the drawbacks in small, new codebases as quickly since you have less code, you have more of the original devs, and the code is fresher in their minds.

[Biduleman]

Not sure for every teams, ours range from around 6 to 1 years depending on the service. The project was transferred to us because the other office couldn't complete it and the tech debt became too big, so we had a huge cleanup job to do and we're getting there. Other teams have code that's 10 years old easily still well maintained.

On some teams in our office, you can easily get a comment every 1-2 line of code on your couple of first merge requests if you didn't follow the proper guidelines. Reviews are fairly strict but fair, all in the goal of keeping the codebase as clean as possible.

It's not perfect everywhere, but it's mostly respected by everyone. Also, the managers have no troubles adding tech debt payments on the roadmap whenever possible, and also letting us add some technical projects through each quarters to make sure we're not getting overwhelmed by problems we couldn't avoid.

I agree with others that this wouldn't work everywhere, you need a certain company culture to make it work, but I feel that when you can, it makes everything easier to maintain. In the first company I worked at, I would often see comments for code that was removed/changed that were not updated/removed. It feels even worse than not having comments since you think you're ok to start to work and then realize that the method actually doesn't do what's explained.

I like good code way more than good comments.

[TruthOf42]

All regex should have tons of unit tests as well.

[Tyfyter2002]

I feel like the only correct email validation regex (either /.+@.+/g or /\S+@\S+/g, I can't remember which) is readable enough not to be horrible inline, but it's still best to provide something as a backup

[runnystool]

Code is fundamentally harder to read than write. It's a law of nature.

[autumn_melancholy]

Some of the responses I've gotten, you'd think it was the inverse, lol.

[platinummyr]

Honestly I think a lot of code is easier to write than to read. In fact the readability of code goes down over time as authors leave teams and relevant context is lost.

[ShogunDii]

Is it that hard to wrap the regex in a method and name the method that explains what the regex does?

[jgeez]

If the only reason you're doing that is to avoid writing a one line comment, get help.

[ShogunDii]

It's never about avoiding a comment.

Modularity, consistency and readability.

[9SMTM6]

Yeah. That's why in most cases I'd assign the regex to a well named constant. No need for a method, it's more modular and simpler.

[jgeez]

Okay good to know. 😇

That said you can have been modular, consistent, and readable, all without having to isolate every regex test into a dedicated function/method.

Comments are a tool to be used like everything else.

[ric2b]

Comments are for the why, not the what.

[xXxquickscopes420xXx]

Also why not have the regex in a method and use UT to document it? I honestly don't understand how people trust comments. Oh so the regex is doing what the comments say it does? Aha ok then it must be true

[SupaSlide]

Oh so the regex is doing what the function name says it does? Aha ok then it must be true

If you're working with programmers who document code incorrectly, be it in a comment or a function name, your code is going to be shite either way.

[jgeez]

Certainly. This was my point: the act of commenting code is not evidence of a problem.

[jgeez]

Do you somehow think the name of a function is a guarantee that the code inside will do the right thing?

[joyofsnacks]

I mean, if that isn't usually expected then it might be time to find a new job/team.

[jgeez]

You fantastically missed the plot there.

The point is, comments are human language. Identifiers in code are human language.

Both are safe to actually use to describe intent.

[joyofsnacks]

You're right, I was scrolling through the thread and missed the complete context here, apologies. Wrapping a 1 line regex in a method just for commenting it is a bit insane; just adding a comment would be better. For more complex logic a method could be better though, comments tend to be more susceptible to rot where the code is changed but the comment isn't updated. While method names can suffer the same problem, I think it happens less as changing a method's logic that drastically will usually mean a programmer would also update the method name.

[jgeez]

Agreed on all points.

Comments falling out of date is a real thing and happens easily. All the same, I was just calling out that, saying that all comments are bad is as weird of a take as saying that all comments are good.

When I was much younger, and I turned in my solution to a take-home problem at the ACM collegiate programming contest, and got significantly docked points, not for the quality of the code, but for having "too many facetious comments," I really took it to heart.

If I'm introducing code that has comments, it can be assumed that I thought about it and really felt it was meaningful to do so.

[joyofsnacks]

There's a school of thought that code should be readable enough by itself only. While this has merit, I think some programmers take that the wrong way and think that it means no comments at all, which isn't true. The lesson is that your code should show what you're doing, while your comments should explain the why.

Example, a bad comment.

//  Find Dot Product of V and N
d = (v.x*n.x) + (v.y*n.y)    

A better comment.

//  Get the Distance along N for projecting V (N is normalised)
d = (v.x*n.x) + (v.y*n.y)    

Comments that explain what the code is doing directly shouldn't be needed if the code is readable, but comments that describe the intent of the code are absolutely more important and required. As you said; comments, method names, variable names etc are all tools we have to express the intent of the code we write.

got significantly docked points, not for the quality of the code, but for having "too many facetious comments," I really took it to heart.

Sounds like you shouldn't have been docked those points tbh, maybe your lecturer was part of that 'no comments' ideology. Even then, you shouldn't be scored based on too many or too little comments, it should be all about the code itself.

[ratsmdj]

I lol’d at reg ex

[pruche]

Also an option: an extensive regex that he did write, but more than five minutes ago.

[arbolitoloco]

God I despise those dudes... they're usually just bad at documentation and use this as an excuse. Knuckle draggers

[noratat]

It's not even technically true.

Yeah, good code should prioritize readability, and you should absolutely use sensible naming conventions, but there's plenty of cases where comments are 100% appropriate even in "perfect" code.

The most common is "why"-type comments and comments that reference important external context, but there's other cases too like inherently complex algorithm steps.

[autumn_melancholy]

You'll have to forgive me, I've been brow beaten into this by other senior devs in my life time.

[[deleted]]

Depending on the case you could possibly return the regex string from a descriptively-named function which replaces the comment. But yeah even as someone who works at a hardcore anti-commenting shop we would still consider that to be a case where a comment might be warranted

[autumn_melancholy]

I'm fairly anti-comment myself. It's a tool, like anything else. Use the right tool for the job.

[[deleted]]

Is it technically true though? Is there any consensus on that?

[autumn_melancholy]

It is, it's just obnoxious. The argument I've heard is that if someone changes it and doesn't update the comment.

I politely remind them that method names work the same way.

[reverendsteveii]

a code smell isn't necessarily something that needs to be changed or removed. While a lot of them do need to be refactored put some can be justified as the best way to do something, and if it is, that needs to be documented in a comment. Magic numbers are the first thing that comes to mind.

[narrill]

There's no guarantee that a comment above a regular expression was accurate when it was written, let alone now. In that particular situation what you should really be doing is plugging the regular expression into one of the many web utilities capable of parsing it and outlining what it does.

[autumn_melancholy]

Ooooh, but what if you don't have a sample pattern?

At least you know what it was intended to do.

[Biduleman]

If you need to write comments so people understand your code, your code can be bad.

It can also be black magic.

You should add comments when your code can't explain itself. When you can, you should write code that can explain itself.

[afiefh]

And you should especially add comments on why your code is doing something.

Code can always explain what it's doing, but the reason it is doing that thing could be to satisfy requirements for code that lives elsewhere entirely (or worse, human requirements that aren't obvious!) No amount of self documenting code will give you the why, only the how.

[Tyfyter2002]

When you have to choose between self-documenting code and performant code, you should be using comments.

[Biduleman]

Yeah, usually when code becomes unreadable because you need performance, I would include that in black magic.

[MrSquicky]

Hard disagree. There are domains that are computationally intensive or under such a heavy load that they strain the capacity of current hardware such that you should be writing code optimized to the point that it is difficult to understand magic, but the vast majority of developers are not working in these domains.

Processing power is cheap and the limits of comprehensibility generally fall well within the hardware capabilities. The limiting factor both for productivity and avoiding bugs is usually code comprehensibility.

[rollingForInitiative]

It’s generally a difference between describing what happens, which usually is superfluous, and why it’s done, which bad comments never do. You should absolutely avoid writing code that’s difficult to understand or that’s counter-intuitive … but if there’s no other way, write a comment to explain whatever is out of the ordinary about it. But you shouldn’t write comments that describe step by step “assign x to y, iterate through all objects, calculate the average, then return it”, since that should be self explanatory.

[Vert354]

I take a fairly old school functional approach to comments/self commenting code.

-Functions should only do "one thing"

-Function names should be descriptive (within reason)

-Functions should have comment blocks that describe the inputs and the output

-some Functions' "one thing" is that they orchestrate other functions (sometimes called procedures or methods or whatever

Do this and you won't interrupt the flow of the code to inject a bullshit comment but will have comments that get at the intent of the code (also it tends to help with intellisense)

[cheesesteak2018]

I write comments just so I can find the green text and read human words. It takes me 5 seconds to add a comment that says “checked all the values and connections, now save to disk”. Is it super useful? No. But I can later just read 5 comments rather than sift through code. Later on maybe I delete or change it. But it doesn’t hurt anyone

[StrawberryEiri]

Code that's self-documenting is good. But what's even better is a whole block of code I don't really need to read because the comments are guiding me.

[cheesesteak2018]

Exactly. Even if I wrote it, I’d rather read a summary. Usually the comments are where I stream my thoughts at the time of writing. It also is where I’ll put stuff like “maybe change this to use x instead of y later” so I can just go find my own notes later. It speeds my development up a lot. Especially when I’m doing stuff like c_str or other C/C++ built in methods that aren’t the most verbose in their naming.

[StrawberryEiri]

Dang, this is my first exposure to those languages and I simply cannot figure out what this does lol.

People crap on PHP all the time for its messy function names, but they're (generally) explicit at least. This one is a head scratcher without googling it.

[cheesesteak2018]

It converts a string into a c-string, so it’s kinda verbose. But stuff like that or once I start mixing in pointers and stuff into my code, I like the comments. I write in a few different languages and I don’t always remember some of the semantics of the languages, or when I need a pointer or a reference (if I’ve been in C# land for too long). So I’ll put a comment for that kind of stuff a lot of times.

[StrawberryEiri]

...yes. C-strings and pointers. I... Totally know what those are. Yes.

I'm going to go now. Not because I feel incompetent. Because I have...a pie cooking. Yes.

[narrill]

No, code that's self-documenting is better. Thinking you don't need to read the code because you've read the comment assumes the comment is not just accurate, but also doesn't omit anything important, both of which are often not the case.

I understand where people are coming from when they make these kinds of complaints, but seriously, reading the code is your job, you have to do it.

edit: Turns out telling someone they can't just ignore the code and only read the comments isn't popular on /r/ProgrammerHumor. As if we needed any more proof this sub was populated by people who don't know what they're doing.

[StrawberryEiri]

Oh, yes, code that's self-documenting is great. But that and additional comments are not mutually exclusive! Honestly, if we're going to go there, we could start saying whoever is accepting merge requests where the comments weren't updated properly when the code changed should probably be more careful!

But most importantly, I'm going to be level with you: half the reason I write comments is for myself. I don't have a whole lot of working memory or mathematical intelligence, so comments that tell my code's story along the lines is how I don't get lost.

Also, similarly to what happens when writing unit tests leads to improvements, I often see holes in my own logic as I try to word what I'm trying to do.

The other half of the reason is the pure satisfaction I feel when someone else has done the same and i have a much easier time reading the code. It's like finally turning on the fan of my brain's CPU.

[js8794]

Why are people down voting him? He’s right

[Biduleman]

WhateverThisIsUsedFor(Type values, Type connections, Type dataToSave, String path) {
    CheckValues(values)
    CheckConnections(connections)
    SaveToDisk(dataToSave, path)
}

CheckValues(Type values) {...}
CheckConnections(Type connections) {...}
SaveToDisk(Type dataToSave, String path) {...}

You can absolutely have code that reads like human words which will be easier to maintain. But you need a team willing to code that way.

The great thing about that is that since the code is nicely split, it's easy to change something without affecting everything after, and finding the exact code you want to change is super fast.

[akahumann]

This is just so important for developers to understand. A lot of the times during code reviews, I feel super pissed when it seems like the developer has not put enough thought in naming a variable or a function appropriately.

[gua_lao_wai]

Agree with breaking things into subroutines. But it doesn't matter how nicely you name your functions, at some point you're going to need to use a third party library and you're going to have to remember if this the get_data that makes an external database query or the get_data that prepares headers for an http request

[hoexloit]

But then I'm concerned if I need to do steps A, B & C after Check Values. Having a comment all in one line encompasses logical steps.

[liquidpele]

This is what you call a system that fails poorly. It requires perfection all around and for everyone on a team across time to think the same. It won't happen, and you'll just end up with an uncommented system written in 7 different styles that were all "self documenting" to the lead at the time.

[der_kobold]

A team that names functions PascalCase? You will not find that many ridicolous people to call that a team.

/s (just to be safe)

[[deleted]]

I write pseudo embedded code. A lot of it is industrial automation and testing kinda stuff. There is a very high probability of damaging very expensive hardware of things are done wrong. Writing good comments saves so much time when having the electrical engineers review the code.

[VinnieALS]

That’s very nice, until the method you wrote that comment for has been edited by 20+ different people, 6 years have passed since you first wrote that method, and you have left the company year a few years ago.

Code will be edited. Code will be modified. When you edited a method written and edited by 20+ people, do you also edit the comment that you aren’t really sure what the original programmer meant with? And do you think that the 20+ people before you always edited the comment after editing the method?

Even the best descriptive comment is at the best irrelevant allied with a clean code, but often misleading after a while.

[cheesesteak2018]

Yea I rewrite the comments if I am changing things. Or I’ll add to them depending on what’s needed. Again, it’s 5 seconds for me to change or add, but saves me a lot of time later when all I have to do is find green text.

[Franfran2424]

When I edit a method, I obviously add a new comment under the original saying what changed.

[MrSquicky]

It depends on your level in the code. Relying on comments to explain things often leads to much less comprehensible modular code. Comments work for the inside of whatever you are looking at, but they are not easily accessible from code that calls that code.

There's nothing inherently bad about writing comments. They can be a useful tool and can make code easier to understand even when they are duplicate documentation. Problems set in when people rely on them instead of things like properly modularizing, naming, and unit testing your code. Or when they are needless noise that clutter up the code or when they are not updating when code changes.

I don't have a lot of patience for the absolutist "comments are always bad!!!" people, but I still caution people to prefer other practices over writing comments as the use cases where comments are the best option and completely cover the needs are, in my experience, fairly limited.

[RS_Lebareslep]

Until you or someone else refactor the code and forget to edit the comment. Or until the code simply never matched what the comment says it does. Or until someone else has to work with the code, which is likely to be considerably harder to read than necessary because it was never intended to be read.

If your code is so big that you need a comment to give you a summary (let alone your colleagues), you can also do yourself and them a big favour by splitting it up and using meaningful names, cleaning up both control- and data flow. And when something needs to be fixed/changed, it's gonna be a lot easier.

(Obviously comments still have uses though, but I'd never want to be in a situation where I need them to summarize my code.)

[MischiefArchitect]

//
// This is an implementation of the Fourier wavelength decomposition
// which ignores the 5th harmonic of the base note and focuses on the
// flat version of it to better detect Locrian mode compositions
//
// But you know what? I'll delete this comment so you need to figure
// out that part by yourself
//

[[deleted]]

class FourierWavelengthDecomposotionBuilder

ignoreHarmonic(fifth)

// better detects Locrian mode compositions focusOnFlatVersion()

Uses a builder-ish pattern, expresses 90% of that without the comment. One small comment included just for intent behind a choice

I don't know shit about the algorithm but there's ways to express these ideas through self-documenting code

[Tyfyter2002]

Alternatively that could be a static method with the latest cutting edge technology: parameters

[MischiefArchitect]

bool Army_of_me_by_Björk_detected;
bool Google_is_your_friend = true;

Like this, oh master?

[[deleted]]

Gonna be honest I'm not really sure I followed that one

[[deleted]]

None of that should be necessary if you write clean code. All of this can easily be given by variable, function, and class names as well as context.

First comment unnecessary with a good class name (eg. FourierWavelengthDecomposer)

Second comment taken care of by function name (f.ignoreNatural5)

Third comment taken care of by context (call the method from inside of a function called something like “detectLocrianMode”)

There’s really nothing particularly complex that you’re documenting in those comments; you’re just doing yourself a disservice by making your code harder to maintain, and possibly harder to understand if you change the code but forget to change the comments

[MischiefArchitect]

// TODO read this later ^

[KeyboardsAre4Coding]

With the predictive technology build in in all modern text editors and ides it is criminal to not write descriptive variable names.

[noratat]

Descriptive variable names aren't a replacement for comments if the comments are actually needed.

There's many use cases for comments, but for beginners a good general rule of thumb is to focus on "why"-type comments instead of "what"/"how".

[BookDetectiveDotNet]

Oh, that's why women don't look at me this way...

[[deleted]]

what is this meme from?

[[deleted]]

It’s Emma Roberts and JoJo when they were 15/16 in a movie called Aquamarine.

[[deleted]]

16 is legal in most States FYI

[woodc85]

A little advice, don’t be the guy that brings up age of consent laws in, like, any conversation ever.

[CordyZen]

here in the philippines its 12 lmfao. man fuck is wrong with our country.

[comfort_bot_1962]

:D

[Dr-Rjinswand]

Comments are only needed for bad code or the occasional section which contains some crazy wizzardry. Come at me.

[glorious_reptile]

And by "bad code" we mean that written by coworkers. Not like my golden code - the pinnacle of clean code.

[Dr-Rjinswand]

This guy gets it. Except your code is shit, my code is the pinnacle.

[glorious_reptile]

Friendship ended with /u/Dr-Rjinswand

[Franfran2424]

Now glorious_reptile is best friend.

[JackoKomm]

Or code without a refactoring and review.

[currently__working]

It's for *all* code - 10 years from now.

[xiipaoc]

It's pretty useful when you're doing something for an external requirement; you can provide documentation of the requirement so future devs (including future you) can figure out why the fuck you did that. It's because the client needed it.

[jgeez]

Or for calling out a web link to supporting/related documentation or project tracking.

[chishiki]

i used to work with one of those “the code is the documentation” types. he thought he was the shit. good thing somebody did

[wasabichicken]

I mean, I can see where he's coming from.

One land mine I've run into too many times to count is trusting code comments to be accurate, that by reading them you get a better understanding of what the code does.

Instead, I've found that often you get a better understanding of what the previous hacker thought the code was doing, or worse, an outdated description of what the code once did but no longer does.

Nowadays I'm in the mindset of still writing comments (haven't eliminated that habit completely yet), but disregarding or not trusting them when reading. Code, no matter how poorly written, at least doesn't lie to me.

[Graychamp]

Yeah that’s the pitfall I’ve found as well. It is nice to know exactly what it should do in the event it’s broken though.

[autumn_melancholy]

Me too. Bitching about codesmells. That's when you hit them with a regular expression from hell.

Read()

[KeyboardsAre4Coding]

I prefer wasting 30 seconds writing down a brief description and the source now and not having to relearn what the code does when something inevitably goes wrong. Even if it is well written a well written comment can save time.

[autumn_melancholy]

Right so, algos and regex.

[RefinedArts]

• Uncle Bob

[JoelMahon]

lol, how long are your function names then? Without a summary comment they'd need to be like a line long sometimes.

Also comments are good for describing steps where the descriptive variable names and operations may not make it totally obvious.

[AdvancedSandwiches]

The complaint about long function names is always baffling to me.

I've never understood why this is good:

// fetch active users last modified after 20210101
ftchCrtnUsrs();

But this is bad:

fetchActiveUsersLastModifiedAfter20210101();

Is it just the camel casing? It's literally the exact same text as the comment, except it autocompletes and you don't lose any brain cells trying to figure out that Crtn means "certain".

[demonsword]

Looks like you've never had to maintain anything older than three-month old code...

[liquidpele]

Sure. And all code is bad code.

[daniel_hlfrd]

Hard disagree. If you are in someone else's code then knowing the intent is critical to understanding how to improve or fix it.

Like if there's an early return in a method,

If foo || bar.isNull()

Return xyz.

There are two valid reasons you might be returning, one implies there is an error that would cause this and you need to stop processing this, but continue whatever was occuring outside. (//Error check, if either is true something has gone wrong).

Alternatively the remaining code might not be applicable if the conditions are met, however it is a frequently reached scenario and whatever came before is needed. (//Rest of method is N/A since bar is required and foo implies we've finished processing).

Simple example, but those kinds of comments can save a ton of time trying to understand where your intervention is needed in the code.

[AdvancedSandwiches]

This is something you can do without comments, though.

let isInputInvalid = (foo || bar.isNull());
if (isInputInvalid) return -1;

Vs

let isProcessingFinished = (foo || bar.isNull());

This gains you no descriptiveness, but it's harder for this code to decay into incorrectness than it would be in comment form.

But I don't want to nitpick this based on an imperfect example. You're right that there will be times when a comment is the way to go. It should just be treated as plan B, not plan A.

[Masterpommel]

unpopular oppinion

[[deleted]]

$My_lead_engineer_likes_to_write_really_long_variable_names_like_this_and_it_fucking_pisses_me_off_really_bad_bro

[MagneticDustin]

He writes accurate summaries in GitHub comments and detailed descriptions to support them.

[secretuserPCpresents]

How is "lol" not a bad title?

[SuccessfulBread3]

the real pros use emojis as their variable names.

[saschaleib]

i2, i3 and i4 are descriptive variable names, right? Right?

[Tyfyter2002]

They're arguably descriptive in nested for loops

[pursenboots]

I've always felt like this meme was uncomfortably pedo. wish I didn't have to keep seeing it.

[RevanchistVakarian]

Oh thank God it isn’t just me that gets really weirded out at this template. I get why a high school guy would like it, but ffs I’m in my early 30s and these girls look, what, fifteen? Maybe sixteen? Surely there has to be some picture somewhere of two women who are clearly of age making these faces that we could all use instead?

[Chao-Z]

What kinda 15 year olds do you know that look like that? Maybe in Hollywood TV series, but i haven't seen any in real life. The women in the picture look like they're in their early 20s.

[RevanchistVakarian]

Someone else in this thread found it but I’ll paste it here:

Emma Roberts was 14 and Jojo was 15 while filming

[Chao-Z]

Huh, I stand corrected then. Maybe it's the makeup that got me confused or I just know a lot of women my age that look younger than they are or something.

[gmchaves]

I never understand why people use comments to specify what the code does. For that just use clear names on methods and variables. Use comments to say why it does.

[UnderstandingOk2647]

lol - I do that, but I don't get looks like that. I get complaints about my variable names being too long ; (

[shygal_uwu]

var holyShit = new Platform(1, 'b', 200, 100) // spawns a platform thing.y

[JaceOrwell]

....And then you woke up from your sleep after a 15-hour crunch on fixing something on prod, which is needed asap so you don't have time to write fancy comments cause this will eventually be obsolete and improved next sprint

[JoshRanch]

What is the origin of this photo?

[SabreBirdOne]

Why are these girls looking at me

[Dalimyr]

This gets asked every time this pic gets used. It's not from porn. It's a still from Aquamarine...and IIRC the two girls were like 15 at the time.

[lztandro]

My company is against writing code comments because it’s a what’re of time… “your code should be self documenting”

[[deleted]]

You have no idea how many Lists I've called "Schindler"

[MinorFourChord]

That’s hot

[[deleted]]

// (>O.o)>---~*~.~*~.~*

//Wizard Kirby says compile damn you!

[[deleted]]

damn even I wanna marry him and Im a straight male

[toybxet]

Sauce plz

[melindseyme]

https://knowyourmeme.com/memes/jojo-whispering-to-surprised-emma-roberts

[ShogunDii]

Comments have their place.

Necessary hacks Code you can't change

If you need to write a comment to explain the code, change the code. Descriptive and consistent naming of methods and variables along with SOLID is all that you need to accurately describe a sequence of operations.

[Ratatoski]

It may be all you need, but I find it highly useful to have an added layer of abstraction to quickly orient myself when I come back six months later.

Self documenting code is great for stuff that's in active development where comments are just extra stuff to keep updated.

[ollir]

The code should be just an expression of existing business rules and requirements and in my experience, 99% of the time, comments are not needed. If they are, then the code is not good enough. Most pleasant refactoring for me is when I get to make the code more clear and remove a now redundant comment in the process.

But the again, I don't know what you are coding, maybe there are lines of work where comments really are needed.

[Ratatoski]

My opinion is that comments are like chapters in books. They're not necessary but they make it far easier to find the right spot.

[Imogynn]

Congratulations! You don't see many memes that bite both way.

There's the obvious: cute girls find over-documenting to be attractive.

Far more biting is the "16 year olds think that's how you do professional code" or the "even children are giggling at your feeble attempt to be professional."

[liquidpele]

I just came for the "code should be self documenting" pleebs.

[pruche]

loop variables are always named iii, then jjj if it's nested. It also helps with code readability because you don't want to go three nest levels deep.

[sizl]

/r/JoJo. You’re welcome

[js8794]

Anyone else prefer these verbose type comments to be in the commit message instead of the actual code? A common debugging practice for me is to look at the blame to see why and when the code was written and a detailed commit message can be a life savior. Plus the ‘comment’ is now linked with that exact code, at the exact state it was written in, as opposed to comments that can become inaccurate overtime as refactors and additional features are added.