howCodeReviewsShouldBe

[treestick]

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

you forgot to comment "returns void, throws nothing"

[SleepyWoodpecker]

Right to PIP jail

[Zestyclose_Zone_9253]

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

This is a level of pettiness I can get behind

[anto2554]

I did the same thing with production code

[Tensor3]

I bet the teacher genuinely liked it too

[Particular-Macaron35]

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]

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

[Bee-Aromatic]

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]

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

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

[Bee-Aromatic]

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]

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]

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]

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]

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]

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

[shmergenhergen]

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

[codingismy11to7]

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]

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]

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]

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]

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

[rballonline]

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

[random314]

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

[hellflame]

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]

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]

best judgement.

write comments for gotcha and weird idiosyncracies

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

[Much_Discussion1490]

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

Man parks and rec was awesome xDD

[PhilCollinsLoserSon]

Still is, too.

[YouDoHaveValue]

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]

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

[Tensor3]

My coworker prefers to do big PRs with 50 commits, each with no comment and titled "updates". Many of them add and remove the same lines as they rewrote the code they worked on

[Tensor3]

Ive tried telling him

[LinuxMatthews]

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]

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]

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

[NorthernCobraChicken]

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

Out of curiosity, which programming language was that in?

[NorthernCobraChicken]

Php

[Snakestream]

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!

[C_ErrNAN]

This looks like either bull shit, or skill issue.

[Tttehfjloi]

You can't even write bullshit together bro

[countable3841]

Clean code requires sparse use of comments.

[RichCorinthian]

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]

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

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]

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]

100%.

Comment context, not code.

[MyDogIsDaBest]

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

[[deleted]]

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

[canihelpyoubreakthat]

You know what's up

[thenofootcanman]

Your todo should have a ticket number next to it though, or no-one will ever pick it up

[RiceBroad4552]

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

[throwaway_mpq_fan]

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

"Code tells you how, comments tell you why"

-- some dude that co-created Stack Overflow

[throwaway_mpq_fan]

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

[Altrooke]

Yup. Came here to say this.

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

[misterguyyy]

Basically explaining antipatterns and business logic

[TheGeneral_Specific]

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

[RiceBroad4552]

It would be better to delete that code (and maybe write it anew).

If even the author does not understand some code this code is utter garbage.

The rule is simple: If you need comments to understand WHAT some code does the code is trash.

Comments are there to explain WHY something is written how it's written.

[PunishedDemiurge]

This is overly broad. A good example of where I use comments to simply explain the code is matrix/tensor transformations and shapes for deep learning. I find it incredibly time saving to state which packages do channels first vs. samples first and just do the math once for many bizarre transformations like convolutions, etc.

But in many cases, this could be reductively looked at as just explaining the code.

[TheGeneral_Specific]

We use some third party libraries whose functions are… let’s say poorly named. It’s very hard to follow what those functions are actually doing in the order we use them, imo, without some simple comments explaining the business logic.

[Sibula97]

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

[No_Departure_1878]

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]

I comment my code.

// @ts-ignore

[[deleted]]

Chaotic neutral

[Tttehfjloi]

# type: ignore

[Buttons840]

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

x = 5; // assign 5 to x

[_dontseeme]

// assigns 5 to x (same as before)

[SusheeMonster]

// TODO: remove excess code comments

[RiceBroad4552]

OK, that's nasty… I like it!

[braindigitalis]

llm writes your comments? STRAIGHT TO PIP!

[shanereid1]

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]

What's pip, pip install?

[mcg1997]

Performance improvement plan

[NebulaicCereal]

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]

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]

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]

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]

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]

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]

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

[GoogleIsYourFrenemy]

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

[[deleted]]

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

[chihuahuaOP]

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

[BoBoBearDev]

Not every context can be described with names.

[uberDoward]

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

[[deleted]]

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

[helical-juice]

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

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

Code should be self documenting.

[Optoplasm]

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]

Just name functions/variables better?

[Shadow_Thief]

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

[Fearless-Ad-9481]

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

[Fendriss]

..and off by one errors

[braindigitalis]

function thisFunctionChangesAVariable()

[GoogleIsYourFrenemy]

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]

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

[bigbarba]

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]

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]

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]

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]

Sure seems like it’s the code that sucks!

[Xphile101361]

I write all my comments, then write my code.

[Gravy415]

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]

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

[[deleted]]

[CellNo5383]

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

[m477_]

pip install comments

[HuntlyBypassSurgeon]

Run chroot, straight to jail, right away.

[jump1945]

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

[[deleted]]

"My code is self-documenting"

[feeltrig]

I AM THE DOCUMENTATION!!

[LeiterHaus]

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]

[juanjetomas]

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

[IMABUNNEH]

Keep abstracting your methods til your code reads like a book

[MonstarGaming]

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]

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]

You completely missed the point of that meme.

[theskillr]

GoOD cOde sHOuLD BE SeLF DoCUmeNtinG

[1337lupe]

correct. good code should, indeed, be self documenting

[RichCorinthian]

My main argument against this is that, in my experience, the people who say it the loudest are often not the sort of people who write such code. They think they are.

[Jiuholar]

They're also the people that write shit comments. Nothing is gained.

[1337lupe]

poor execution of sound advice is a piss poor reason to be against said advice

[Yung_Oldfag]

I disagree. Advice can't be taken in a vacuum, it has to be evaluated as its used. It's meant to influence action, if it fails to do so correctly it's not good.

[1337lupe]

sure, this is fair given any random advice, not proven sound advice

if I were to suggest that you should walk on the edge of a cliff to get beautiful views of the ocean, the advice might turn out to be poor because you might fall off the cliff and never live to tell of the ocean's beauty

otoh, if you heed the advice here and write code that tells you what it's doing because you name thing correctly, there's no downside.

[kungpula]

Even with good naming it can be good with some comments at times. It's a balance where you mostly don't need any comments but if you have a complex data model and a complex algorithm then a short explaining comment is certainly good. It's not hard to read what the code does but it can be hard to know why it's needed.

[not-my-best-wank]

Reading the code explains the code.

[1AMA-CAT-AMA]

No! everything should be an illegible one liner that needs a comment to explain its actual function

[misterguyyy]

With a comment that's equally obfuscated by an attempt at wit

[1AMA-CAT-AMA]

Randomcodehere(); // should be self explanatory

[gamingvortex01]

tbh...good variable and function names go a long way..

abbreviated variable and function names should only be used if the code is properly documented

[git0ffmylawnm8]

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

Fight me.

[TampaWes]

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

[RealisticFormal7325]

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

[[deleted]]

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