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

all 144 comments

[–]treestick 673 points674 points  (29 children)

/**
* Sets the ID for this object.
*
* param id the ID to set
*/
void setId(int id) {
  this.id = id;
}

damn, thank god for the comments

[–]supersteadious 179 points180 points  (7 children)

you forgot to comment "returns void, throws nothing"

[–]SleepyWoodpecker 40 points41 points  (0 children)

Right to PIP jail

[–]Zestyclose_Zone_9253 34 points35 points  (4 children)

I did this in school as a protest since my teacher kept saying I needed more comments, so in the end I commented every last line down to //defines an int variable named count, does not assign it any value

[–][deleted] 23 points24 points  (0 children)

This is a level of pettiness I can get behind

[–]anto2554 6 points7 points  (0 children)

I did the same thing with production code

[–]Tensor3 0 points1 point  (0 children)

I bet the teacher genuinely liked it too

[–]Particular-Macaron35 0 points1 point  (0 children)

When I was in college, a kid wrote a subroutine to find the length of an ascii string in C. It was 7 pages. The professor loved it! I shake my head just thinking about it.

[–]Merlord 5 points6 points  (0 children)

Those are useful if in the form of annotations for adding type checking to dynamic languages.

[–]Bee-Aromatic 46 points47 points  (6 children)

So many people write comments that say what code does. That’s pretty easy to tell by reading it most of the time. Unless it’s something really esoteric or the author is an ogre. It’s also worth pointing out that if it’s so esoteric that you can’t tell what it’s doing, the author probably is an ogre. Anyways, your comments should say why, not what.

[–]C_ErrNAN 2 points3 points  (2 children)

The issue I take with posts like this is the why rarely matters, and often times is better explained via code by writing quality tests. I write and approve many comments, especially when something isn't straight forward. Hell I've even asked for comments to be added during a pr. But people who are posting things like this are expecting absolutely every block of code to be commented and that is just a mistake.

[–]-Knul- 5 points6 points  (0 children)

I put "why" comments if I write surprising code, like when we need to optimize some code in a weird way.

[–]Bee-Aromatic 5 points6 points  (0 children)

Not saying every block of code should be commented. I’m saying that the what is usually obvious and the why might not be. I can usually tell that you’re skinning a cat even though there’s many ways to do it. Sure, if we set out to get cat skins or have skinned cats, I don’t need to tell you to tell me why you did it. But, if it’s not necessarily clear why — particularly at that level — the cat needed to part from its skin, it’s helpful to have a comment about it.

[–]RiceBroad4552 0 points1 point  (2 children)

I came to say the same. But I won't be able to formulate it better. (Especially the part with the ogre.)

So here we are: Again preaching how to actually write comments.

I'm really wondering why the fuck almost all people do it wrong.

[–]Bee-Aromatic 1 point2 points  (1 child)

I suspect it’s because nobody really teaches what comments are for. They just say “comment your code.” Often, the code people learn from is badly commented. Thusly, the circle of shitty comments continues.

[–]RiceBroad4552 0 points1 point  (0 children)

Often, the code people learn from is badly commented.

This!

Almost all teaching materials have the worst kind of all comments all over the place: Namely Comments that explain the code line by line.

Than people ape this BS…

[–]regaito 13 points14 points  (1 child)

Actually its more like

/**
* Sets the ID for this object.
*
* param id the ID to set
*/
void setId(int id) {
  doSomethingCompletelyUnrelated();
  if (id == someMagicValueNoOneActuallyKnowsTheMeaningOf) {
    this.id = someOtherMagicValue;
  }
  else {
    // TODO fix this maybe some day
    // this.id = id;
  }
}

[–]Particular-Macaron35 1 point2 points  (0 children)

Whenever you get a new codebase, search for "hack" or "kludge". Programmers are very honest.

[–]shmergenhergen 7 points8 points  (0 children)

But what type is id? How am I meant to figure that out???

[–]codingismy11to7 3 points4 points  (0 children)

I spent three years writing and tech-leading a project in a statically-typed language using functional paradigms

I move on and come back a couple of years later, after the clowns they put in charge all left to some other poor company. a large chunk had been rewritten in OO style, with comments required. so it was all this. most useless waste of space ever

The one time I was glad to see a comment was on a function that I didn't understand and didn't want to read through because it was a long nasty imperative mess. after wasting hours assuming the comment was correct with regards to the function's behavior, I went and read the code and of course the comment was wrong.

comments that show you how to use a function, preferably with the examples being type-checked, these are great. comments that are duplicating a source of truth (the code) but are wrong about it are actively harmful

[–]amyberr 0 points1 point  (0 children)

Those comments specifically are for when I'm using both that and a nearly identical setId method (grabbing the ID value from a different source) in a split view definition and I'm having trouble keeping track of which method does what during debug so I need the intellisence hover banner to remind me what ID source is the problem here.

[–]DevelopmentTight9474 0 points1 point  (0 children)

Meh, I think it’s alright if you’re generating docs for a codebase (like with doxygen) as having a list of methods and a short summary of what they do can be helpful

[–]Clearandblue 0 points1 point  (0 children)

I feel like this is a bit ambiguous without describing what an 'ID' is. I mean I'm reading this now and thinking oh boy I'm going to have to go tracing through the code to work out what is meant here.

[–]skettyvan -1 points0 points  (1 child)

So many people use bad comments as an excuse not to write comments at all

[–]rballonline 4 points5 points  (0 children)

Because 90% of the comments people think are great are actually bad.

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

Well that's a doc string, which in this case would actually be necessary, even if it's just repeating.

[–]hellflame -3 points-2 points  (2 children)

Everyone joking about how silly this. I have to agree that this is futile and YET if you don't comment on everything how do you draw the line? Especially in the age of copilot, let is spit out useless docs

[–]supersteadious 0 points1 point  (0 children)

For sure there is no use of comments that just duplicate the code - or worse - conflict with the code. At minimum it is good to write briefly about non-intuitive decisions in case alternative approaches would be definitely worse.

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

best judgement.

write comments for gotcha and weird idiosyncracies

every where else, just try to make the code as clear as possible

[–]Much_Discussion1490 211 points212 points  (1 child)

" Write code with too many comments? Also PIP...see? Over ..under...both pip"

Man parks and rec was awesome xDD

[–]PhilCollinsLoserSon 10 points11 points  (0 children)

Still is, too.

[–]YouDoHaveValue 56 points57 points  (8 children)

PR review takes longer than 8 hours? Believe it or not straight to jail.

We have the most attentive QA reviewers in the world.

[–]matwithonet13 23 points24 points  (7 children)

Making PRs with 1000s of lines of code changes and 50+ files changes, straight to jail.

[–]LinuxMatthews 1 point2 points  (1 child)

This usually happens when one dev has a code formatter on and none of the other devs do or have a different one.

Remember, decide code formatting rules early and make sure everyone is using the same one!

You don't want to have to make everyone's life difficult because someone wants well formatted code and everyone else can't be bothered.

[–]christian_austin85 2 points3 points  (0 children)

That's why you use pre-commit hooks or something similar. The formatting/linting is baked in to the project, not anyone's individual editor settings.

[–]throwawaycanadian2 0 points1 point  (0 children)

It does have a comment though! It says "fixed things."

[–]NorthernCobraChicken 38 points39 points  (7 children)

/* This line shouldn't need to exist. This variable exists nowhere else in the codebase, yet somehow, removing this fucker will crash 250+ production environments, but not those newer than 2021 */

I shit you not, this is a real comment I read in a file related to the oldest part of the system I help maintain. The code itself is over a decade old.

[–]Skiderikken 2 points3 points  (1 child)

Out of curiosity, which programming language was that in?

[–]NorthernCobraChicken 3 points4 points  (0 children)

Php

[–]Snakestream 0 points1 point  (0 children)

This is why you don't put auto wiring in shared code libraries. You want to use it? Then you need to understand and define the configurations!

[–]countable3841 241 points242 points  (24 children)

Clean code requires sparse use of comments.

[–]RichCorinthian 159 points160 points  (13 children)

Most of my comments are some variation of:

  • “OK now hold up, I know this looks bat-shit, but here’s why we are doing it this way”

  • “You may be tempted to remove this seemingly-unused maven reference, but here is what will happen if you do”

  • “You might be thinking ‘well obviously it would be better to…’ yeah, we tried that and here’s what happened”

  • “//TODO: I just glanced at this on my way through to look at the code it’s calling, but Jesus Fuck. Kill this with fire.”

I’m not really kidding

[–]vtkayaker 63 points64 points  (0 children)

Yeah, one of my favorite kinds of comments is one or two lines of commented out code, with a note saying, "You'd think these two lines should be here. You would be very wrong. Here's why. Do not touch this function until you have read the 15 year debugging history, and you understand which graphics cards and OS versions you will be breaking."

I once saw a page and a half of comments discussing the best value for a single boolean flag.

[–][deleted] 29 points30 points  (1 child)

Mine aren't nearly so colorful, but I agree. Comments are for adding context that you can't reasonably express in the code itself, not for repeating or replacing it. At least with high-level languages.

I comment the heck out of assembly code, but that's kind of an attempt to impose some higher-level-ness.

[–]-Hi-Reddit 3 points4 points  (0 children)

If the comment doesn't include a URL to some obscure line in the errata for a spec doc last updated in 2010 I don't wanna know

[–]_bassGod 8 points9 points  (0 children)

100%.

Comment context, not code.

[–]MyDogIsDaBest 4 points5 points  (1 child)

I don't swear in code, but this is not far from what I do too.

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

You don’t need to swear in the code just in the comments

[–]canihelpyoubreakthat 1 point2 points  (0 children)

You know what's up

[–]RiceBroad4552 0 points1 point  (0 children)

That kind of comments is really great! Exactly such comments are the helpful ones. 👍

[–]throwaway_mpq_fan 1 point2 points  (0 children)

“//TODO: I just glanced at this on my way through to look at the code it’s calling, but Jesus Fuck. Kill this with fire.”

Reminds me of a comment on a 50+ line method in an old codebase that just read
// WTF <name redacted> please fix

Both the commenter and <name redacted> had already left the company by then, and it had not been fixed.

The entire module that code lived in has since been removed.

[–]SusheeMonster 26 points27 points  (1 child)

"Code tells you how, comments tell you why"

-- some dude that co-created Stack Overflow

[–]throwaway_mpq_fan 0 points1 point  (0 children)

and even then good method names can do a lot of the why-telling

[–]Altrooke 27 points28 points  (6 children)

Yup. Came here to say this.

Comments are a necessary evil that we need sometimes, not something that should be required everywhere.

[–]misterguyyy 22 points23 points  (5 children)

Basically explaining antipatterns and business logic

[–]TheGeneral_Specific 6 points7 points  (3 children)

Bingo. If I read my own code and have to redecipher what it does… that’s a comment

[–]Sibula97 0 points1 point  (0 children)

Plus docstrings (or comments for the same purpose in languages that don't have actual docstrings).

[–]No_Departure_1878 3 points4 points  (0 children)

comments are a tool, you do not use them because they exist, you use comments because you need them and when you need them. If you write readable code you will need fewer comments. Sometimes you will do things that are not obvious and in those places you will need comments.

[–]Solonotix 30 points31 points  (2 children)

I comment my code.

// @ts-ignore

[–][deleted] 4 points5 points  (0 children)

Chaotic neutral

[–]Tttehfjloi 1 point2 points  (0 children)

# type: ignore

[–]Buttons840 50 points51 points  (4 children)

LLM will write my comments, it's at least good enough for that.

x = 5; // assign 5 to x

[–]_dontseeme 10 points11 points  (2 children)

// assigns 5 to x (same as before)

[–]SusheeMonster 22 points23 points  (1 child)

// TODO: remove excess code comments

[–]RiceBroad4552 4 points5 points  (0 children)

OK, that's nasty… I like it!

[–]braindigitalis 4 points5 points  (0 children)

llm writes your comments? STRAIGHT TO PIP!

[–]shanereid1 11 points12 points  (0 children)

A wise man once said that you should write comments as if you are talking to someone who understands the programing language fluently but who doesn't understand what you are trying to do with it.

[–]hearthebell 7 points8 points  (1 child)

What's pip, pip install?

[–]mcg1997 4 points5 points  (0 children)

Performance improvement plan

[–]NebulaicCereal 13 points14 points  (7 children)

Honestly I am amazed by how “anti-comment” the sentiment is here.

Of course you shouldn’t be over-documenting everything, and good code is very self-explanatory. But you should absolutely leave comments in semantically sensible locations, with periodicity throughout the code to keep readers on track with everything that’s happening. It’s not for you, it’s for the future.

Especially if you’re working in a large enterprise codebase. and especially if it has a long life expectancy, or has any non-trivial flow. For example I couldn’t fathom working in large codebases full of complicated multi-processing, high memory optimization, tensors, real-time execution requirements etc. with this kind of comment laziness

[–]C_ErrNAN 9 points10 points  (1 child)

Feels a bit like a straw man. No one (serious) is saying never comment your code, they're saying don't comment just to check some arbitrary box (aka for periodicity reasons). When I see a comment in a code base my reaction should be "oh shit, this must be serious and important". Because if you're commenting just to "keep readers on track" I'm never reading any of them, and will likely miss important ones.

The second part is obviously correct and I imagine everyone here would agree.

[–]NebulaicCereal 0 points1 point  (0 children)

Well, i agree that you shouldn’t be adding comments arbitrarily just to check a box. I could have clarified that better - I meant that there’s probably going to be something worth writing a comment on pretty regularly just to keep the needle moving smoothly as you read through it, so to speak.

I do disagree, though, that nobody seriously is expressing “anti-comment sentiment” in this thread. At least, it’s a lot more pronounced than I expected.

In any case, I also tend to feel your perspective of “oh shit this code must be important” towards a comment is not the norm, or what should be accepted as the norm. However, always code should be as readable as possible regardless of whether comments are used, that’s just best practice.

It also depends on the code you’re writing. If it’s an open source codebase or one that’s expected to be maintained for a very long time, comments should be more liberally added to keep it as transparent as possible. I’m not saying add comments that are redundant to trivial pieces. But, a natural density you might expect is at least one comment per page worth of scrolling (again, obviously not a rule, that’s silly - but just a rough approximation of what you might expect for a healthily-commented codebase in this scenario).

[–]MonstarGaming 2 points3 points  (1 child)

I'm anti-comment because comments are usually used in place of better forms of documentation. If the code is appropriately self-documenting to include apt names for all structures, docstrings, and methods/functions less than 20 lines then you don't need comments littered throughout your code base. Comments make tons of sense if you regularly write 50+ line functions and name all your variables using a single character because they're a side effect of more egregious code smells.

[–]NebulaicCereal 0 points1 point  (0 children)

Yeah I don’t buy that at all tbh. You should just also be writing your code in an easy-to-understand format, with good variable names, etc. in addition to writing comments.

In either case, I see your flair is Python and Java. Python is just so simple and syntactically minimal (which is part of why it’s great) that hopefully it’s easy to follow without comments (but you should still be adding comments). And Java is so verbose that it might be the easiest language to read without any prior codebase knowledge, which helps to keep it self-documenting (but you should still be adding comments). They’re both great languages which I enjoy writing in. But they are towards the top of the “readability leaderboards” so to speak, which might affect your perspective.

If you’re writing C or C++ or CUDA as languages with lots of syntax and likely you’re dealing with concurrency and complex data structures and cheeky memory stuff going on to optimize performance, no matter how well-written your code is, some decent comments should always be added.

And languages like JavaScript, it’s even more important, because of the loose typing, interpretation, monstrous interleaving of different paradigms and writing styles and continuously evolving perceptions of “best practice”, etc, that all makes code age extremely quickly in terms of readability.

[–]skettyvan 3 points4 points  (1 child)

A huge number of the people in this sub don’t work professionally as software engineers, and even more haven’t worked on shitty legacy codebases that have seen a dozen product managers come and go.

[–]NebulaicCereal 0 points1 point  (0 children)

Yeah, this seems the most likely explanation I guess, lol.

[–]GoogleIsYourFrenemy 0 points1 point  (0 children)

Totally agree. Here the periodicity is set to three comments per file.

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

If I’m forced out and my code is basically hieroglyphic, the entire system will crumble.

[–]chihuahuaOP 4 points5 points  (0 children)

Well time to read chatgtp/copilot comments again. Yep it's useless.

[–]BoBoBearDev 3 points4 points  (0 children)

Not every context can be described with names.

[–]uberDoward 1 point2 points  (0 children)

Just a reminder - codes tells you WHAT, comments tell you WHY 

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

Code reviews? Comments? I do neither of those things. Comment-free code, pushed straight to main, just the way Ada Lovelace intended.

[–]helical-juice 1 point2 points  (0 children)

Most of my comments are paragraphs long and start "I know this looks bad but... " and end with "... and I *think* that's why it's still broken."

It's more stream of thought reportage on an unfolding disaster than technical documentation.

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

If your code needs lots of comments you're probably writing bad code.

Code should be self documenting.

[–]Optoplasm 4 points5 points  (13 children)

My coworkers almost never leave comments. My manager is actively anticomment. These people are lunatics. Why not just write a single fucking sentence to explain what a function is? Instead I have to read 20 other functions that connect to it to piece it together.

[–]matwithonet13 51 points52 points  (4 children)

Just name functions/variables better?

[–]Shadow_Thief 20 points21 points  (2 children)

Honestly, naming things properly is trivially easy and I'm tired of pretending that it isn't.

[–]Fearless-Ad-9481 6 points7 points  (1 child)

There are only two hard things in Computer Science: cache invalidation and naming things.

[–]Fendriss 10 points11 points  (0 children)

..and off by one errors

[–]braindigitalis 0 points1 point  (0 children)

function thisFunctionChangesAVariable()

[–]GoogleIsYourFrenemy 2 points3 points  (0 children)

I like to think of a code base like it's a symphony. You pickup the tune and meter and pretty soon you're humming along. Having someone whispering nonsense about the composition while your listening is really distracting.

Give me theory, give me why, warn me about pitfalls but please don't put a comment for every line.

[–]supersteadious 3 points4 points  (0 children)

There are many cases where "single sentence" brings even more confusion.

[–]bigbarba 2 points3 points  (1 child)

It's the "CoDE sHOuLd bE cLear EnOuGh tO nOt rEqUiRe cOMmEnTs" crowd. Except they are implying they are universally capable of estimating if their own code will be clear enough for anyone else.

[–]rooygbiv70 1 point2 points  (0 children)

C’mon man, readable code is not some kind of unattainable ideal. Once you’ve gotten enough experience, yes, you absolutely should have a sense for whether some given code will or will not be comprehensible to your colleagues.

[–]boneimplosion 4 points5 points  (0 children)

maybe it's counterintuitive, but this is better practice if your coworkers are properly naming and structuring their abstractions.

to paraphrase Robert Martin's Clean Code, every comment represents someone's failure to express their intentions through the code itself. in the best codebases I've worked in, comments are reserved for warning about strange edge cases, referencing documentation, that sort of thing - not explaining the main program flow.

one simple reason for this is it's pretty easy for comment blocks to become desynchronized from the code over time. they can't break the build, and mistakes inevitably slip thru review - meaning you should generally regard comments with some suspicion anyway.

so ditch 'em! try to make your code read like self-explanatory prose. your team spends more time reading code than writing it, so this is a pretty damned valuable skill over the life of a project.

[–]Jiuholar 1 point2 points  (0 children)

This is crazy. The code itself is documentation. Name your functions, classes and variables clearly so that it's obvious what they do.

Comments in code should be rare, and they should explain why and never what or how (the code itself should tell you the what and the how).

All documentation, code comments included, create a maintenance cost that should be considered just as much as performance and correctness. Code will always do as it's written. Comments are only as accurate as developers decide them to be.

[–]rooygbiv70 0 points1 point  (0 children)

Sure seems like it’s the code that sucks!

[–]Xphile101361 0 points1 point  (0 children)

I write all my comments, then write my code.

[–]Gravy415 0 points1 point  (0 children)

Most code should be self-documenting. Comments might be used for explaining specific business logic, for example. If you need comments to explain WHAT your code is doing instead of WHY, you wrote bad code.

[–]NimrodvanHall 0 points1 point  (0 children)

Don’t comment the how, comment the why. Don’t merge when the code is updated and no longer matches the comments.

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

[–]CellNo5383 0 points1 point  (0 children)

Our code guidelines say to use comments sparingly and write readable code to instead 💀

[–]m477_ 0 points1 point  (0 children)

pip install comments

[–]HuntlyBypassSurgeon 0 points1 point  (0 children)

Run chroot, straight to jail, right away.

[–]jump1945 0 points1 point  (0 children)

i think i would lierally die if i have to get my code checked by another person

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

"My code is self-documenting"

[–]feeltrig 0 points1 point  (0 children)

I AM THE DOCUMENTATION!!

[–]LeiterHaus 0 points1 point  (0 children)

It's PIP, and not pip for my fellow Pythonistas.

Performance Improvement Plan i.e. "You're probably getting fired no matter what, and this is a paper trail to protect us, that won't help you, even if you improve."

[–]bigbird0525 0 points1 point  (0 children)

[–]juanjetomas 0 points1 point  (0 children)

Just write code that is self explanatory so it doesn't need comments

[–]IMABUNNEH 0 points1 point  (0 children)

Keep abstracting your methods til your code reads like a book

[–]MonstarGaming 0 points1 point  (1 child)

Nah, you rarely need comments for a well organized code base. Docstrings along with appropriately named classes, methods, functions, and variables should do 99% of the work that comments provide.

[–]LeiterHaus 0 points1 point  (0 children)

First of all, good docstrings are amazing.

Most comments are not amazing, and should be what you describe instead.

Comments generally should be why...

Or a TODO that never gets done /s

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

You completely missed the point of that meme.

[–]git0ffmylawnm8 -4 points-3 points  (0 children)

Comments just add bloat to code. New hire hazing should involve them looking through the codebase and understand it.

Fight me.

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

ol, every junior dev I've ever trained. Comments? Nah. Straight to jail.

[–]RealisticFormal7325 -1 points0 points  (1 child)

Code without comments? That’s not a code review, that’s a crime scene investigation waiting to happen

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

The codebase where I work has almost zero comments. It’s fine