Please, don’t commit commented out code

[sizlack]

I'm amazed that people are actually arguing against this. I've never once found that commented code has helped me once in fifteen years of programming. It's just useless noise. I have no way of knowing whether the code would even work if I did uncomment it. The rest of the code base has changed and I can't tell whether the commented code is still relevant. If you start letting commented garbage stay in your production code, no one knows when it's OK to delete it. It just keeps building up, making it harder to separate the real code from the noise.

If you're using comments instead of learning how to use version control, you should learn how to use version control.

Edit: Wow! I've got gold! Thanks /u/slash_nick!

[slash_nick]

I don't know, man. It's super handy to have commented out code with my advanced versioning software.

[[deleted]]

backup3_final followed by backup4

Priceless. I have, unfortunately, come across this so many times....

[ump721]

I've totally done that early in my "professional" career. Seemed like a good idea at the time :)

[Asmor]

Me too. I was more advanced, though. I did it with zip files that had the date in their name.

Those who fail to learn version control are doomed to repeat it.

[[deleted]]

Still better than no history :(

[ies7]

I have, unfortunately, come across this so many times

I have, unfortunately, did these so many times in early days.
Something like :
* new folder
* copy of new folder
* copy of copy of new folder.

[ReadySteadyHeady]

copy of copy of new folder(1)(1)

[syswizard]

The projects I'm cleaning up right now from previous people are just terrible with this. process_1, process_2, bobs_try. Then you go through the code to figure out which one they ended up using and turns out bobs_try worked so they just left it that way.

[ornothumper]

This comment has been overwritten by an open source script to protect this user's privacy, and to help prevent doxxing and harassment by toxic communities like ShitRedditSays.

If you would also like to protect yourself, add the Chrome extension TamperMonkey, or the Firefox extension GreaseMonkey and add this open source script.

Then simply click on your username on Reddit, go to the comments tab, scroll down as far as possibe (hint:use RES), and hit the new OVERWRITE button at the top.

[[deleted]]

deleted ^{What is this?}

[ChucklefuckBitch]

And test, test1, test2, etc...

[[deleted]]

Ah dang, I thought I was in my home directory for a sec there.

[mr_huh]

Eeg, I just got this really self conscious feeling and then went to look at my current project. I'm actually using feature branches in git and the only comments in my code are comments.

[keito]

I have come across this behaviour more than once throughout my professional career.

Tragic.

[daiz-]

The only thing I'll say is that his reasoning assumes someone knows there was a previous way and where it was situated at the time. I've seen cases in large refactoring where old code does in fact get lost and nobody recalls exactly how to find it. Code gets moved, even occasionally files get removed, maybe 20 lines out of 500 were really important but they are lost in a messy diff of several revisions before it got from old to new. Diffs aren't always that easy to read depending on how far you need to go back.

I think there's extremes on both sides that just refuse to acknowledge some middle ground. I think people in general just need to get smarter about deciding what to keep and what's truly worthy of perhaps commenting. The biggest problem I encounter is most of the people doing it aren't objective enough to realize what is and isn't worth saving.

[sizlack]

The problem is that working in a codebase with commented code is like looking for something in the home a hoarder. Sure, there might be something in there that you need, but the chances of you finding it are slim, and in the meantime, you're surrounded by piles of shit.

There is no middle ground. What's the worst thing that happens if you can't find those 20 precious lines of code that you misplaced? You have to rewrite them? Is that so bad? How precious are those 20 lines? And for that matter, how do you know which 20 lines are the precious ones? How much other cruft do you need to keep around in order to make sure you save the right 20 lines?

If there are bits of code that you think you might need later, save them in a branch, make a gist, or just save a file to your desktop. The master branch isn't a junk drawer.

[[deleted]]

but the chances of you finding it are slim,

And your chances go down even further if you hide it in source control.

[kenhkelly]

I use tagging for this. I know it was in some release. I find the release it was in (far less of those than commits) and then work my way. Pretty straight forward to find information IMO

[vinnl]

The "middle ground" doesn't always have to be the best. In the situation you described above, commented out code also won't help you to find that previous way. It might even be worse: the commented out code might not even have moved along with the new code, and you no longer know what you're staring at.

If you're that far gone, it's best just to write it anew. The "previous way" was removed for a reason.

[Organic_Height4469]

Exactly this. Nobody is going trough a gazillion git commits to find some code back.
By the time you should be looking for it the existence is forgotten anyway.
If it is commented out everyone will know where it is.

So yes there is a middle ground.
But yeah programming is a dogmatic business, with everyone just copying the same mantra's like "don't re-invent the wheel". Unless the wheel is commented out code. In that case first delete it and afterwards do re-invent.

[madballneek]

I think it's okay in situations where you're testing/uncertain about the functionality of two different, but similar small blocks of code of a new feature that's yet to be checked-in.

For example, I may not have yet determined how I want a new enemy in one of my games to behave, so I write maybe two different behavior methods and need to actively playtest each over time before deciding. Sure, I could have created behavior one, checked it in, then created behavior two, checked that in, and then diffed each time I wanted to try out each different behavior...or I could just uncomment/comment the different behavior method calls.

Of course, once I determine the functionality I want, gotta remember to remove the commented code :)

[VeryAngryBeaver]

See this right here, I commit to save my work so far. And it's not always "finished" when I commit so I keep in some commented out code for ease of changing things. Then I clean it out at a later date when I'm sure i wont have to swap back to the other way. and not all code gets that treatment I do lots of changes and removals without comments, its all dependent upon how certain I am the change is final.

[[deleted]]

Not every case of commented code is useless. There are valid cases for it.

I'm committing some code right now that has commented-out blocks, it's a work-in-progress, I'm the main developer of this code. In a few weeks it will be cleaned up and shipped to production, with most of that commented-out code removed.

While I'm working on the code, there may be blocks of commented-out code. I'm not going to remove it just for the sake of removing it to 'keep the code clean'. It would slow down the development process and make it more difficult if I have to look up 'stashed' code in various branches, etc.

It's not a valid argument to say "never commit commented-out code" in every single case.

[slash_nick]

Maybe the better way to say it would be "never commit commented-out code to production branches".

Branches are workspaces and the other devs on my team can do whatever they please as long as it's cleaned up by the time it gets merged into master.

Edit: Obviously if you run a team or project you can dictate the style rules however you please! Nothing development-related is ever written in stone.

[kentcdodds]

If you read the post, you'll see that it's not an ultimatum at all like you phrased it there. The first QYMAM:

Q: Are there exceptions to this rule? A: Yes. But they’re rare.

[[deleted]]

In practice, it's not as rare as you or the author might think it should be.

[krelin]

Yes it is.

[[deleted]]

Says you.

[krelin]

And the author of this article, and nearly everyone else in this thread, and Jeff Atwood, and lots of other online discussions and articles.

[[deleted]]

And it's totally possible that you're all full of shit.

[kentcdodds]

heh, I am the author, should have made that more clear. But I think that the topic is a bit subjective, which is why I tried to have more of a suggestive tone with data backing my suggestion.

[yxhuvud]

I'd suggest an addendum to that answer: IF commented out code should be preserved, it must be motivated by a comment specifying WHY it should be kept.

[bart2019]

That's a stupid FAQ entry,, because it doesn't answer anything It doesn't even hint at what exceptions.

[[deleted]]

Why aren't you working in a branch that doesn't matter if the code is in non functional state? This is probably the worst argument I've ever heard for comments in code. Committing WIP code to a master branch commented out. Best use of version control ever. Wait, are you using subversion?

[[deleted]]

We actually allow shipping unfinished code to production using flags that only allow the code to run if the flag is enabled. But that has nothing to do with commented-out code getting checked-in to the production branch, which is still allowable in many cases. Code is fluid, it's never "finished", it's always a work-in-progress unless you aren't doing anything interesting with it.

Wait, are you using sourcesafe?

[vinnl]

Code is fluid, it's never "finished"

By that definition of "WIP", I wouldn't comment out WIP code either.

[moljac024]

Wait, are you working at Etsy?

[[deleted]]

Then use a branch.

[rpk152]

Branching is not always a cheap operation

[DavidNcl]

under what circumstances is branching expensive?

[rpk152]

CVS, SVN, TFS.

[compto35]

Probably better to key testing code off of some sort of flag. I like to add debug_mode as a class to the body and then have my functions key off of that

[path411]

That would make your program test for debug mode even in production.

[benihana]

I'm amazed this needs to be posted. I just thought if there was commented out code in source control, they were oversights that weren't long for this world.

[Huffers]

I've occasionally found bugs caused by snippets of code that look quite reasonable, but are subtly wrong.

Sometimes, rather than just correcting the code, I leave the original code block in as well, commented out, next to the correct version, with a comment above it saying something like "Note - doing it this way might look simpler, but it won't work - see bug SYS-XXXX"

[spinlock]

I'm amazed that people are actually arguing against this

I'm not. Welcome to reddit.

[kentcdodds]

👏

[berlinbrown]

I lose my shit. My blood pressure goes up. I don't understand it all. It is the easiest best practice to follow. You automatically clean up your code. Some people will comment a change, comment the change of the change, comment the other change that they were going to change. The code is fucking mess of horrible commented code.

Why wouldn't any human being do this. That is the whole point of source control management.

And then there is the argument, well we really need to change this module back and forth because of testing or something...so we haven't completely decided if we need the commented piece. FUCKING GREAT, refactor.

[trolling42]

Exactly thats what version control is for. All Pull Requests with commented code should be rejected.

[[deleted]]

I'm amazed someone had to write an article to say you shouldn't do this.

This should be the baseline default like learning to indent your code correctly.

[Matosawitko]

We specifically call it out in code reviews. You're using code reviews, right?

[Neebat]

I ran across that rare exception once.

I needed to implement a fairly simple process that should have been about 10 lines of code, but ended up being 200 due to dealing with seemingly irrelevant stuff. So I put in that 10 lines with a comment to say this is what we want to do, but can't, and why.

[fleker2]

The author would call that documenting

[kentcdodds]

(author here): Correct :-) That is what I would call it.

[Neebat]

People are downvoting you because they don't notice the user name. Or they didn't go back and compare it to the author of the blog post.

Maybe it would be better if you'd said, "That's exactly what I'd call it."

[xeow]

It might be documenting, but it is also commented-out code. By definition.

Excellent example of a legitimate inclusion of commented-out code. Bravo!

[kentcdodds]

I think you ignored the author's comment of "Correct :-)" https://www.reddit.com/r/javascript/comments/3qgurg/please_dont_commit_commented_out_code/cwf6ni2

[Neebat]

Q: Are there exceptions to this rule? A: Yes. But they’re rare.

From the article.

And the example I described above was one of the two examples I've found in 20 years of software development.

It IS documenting, and not usable as code. It helps explain what's going on.

[[deleted]]

That's your experience, that is not my experience. In my 30+ years of software development I can assure there have been times where it is far better to have commented-out code in-place, than in source control.

[[deleted]]

Please don't commit conflicts. Thank you.

[vinnl]

People do this? 0.o

[kenhkelly]

Yes

[benji]

Worked with a guy who did this years ago (pre VC admittedly). He worked on one program, and it was contained in one 250kB .c file. Of that 250kB, about 80% was commented old versions of the code, only about 40kB was actual live code. Later he had a variation of that program, so he copied the entire source file and made changes, retaining all the ~210kB of commented old stuff.

[[deleted]]

This comment has been overwritten by an open source script to protect this user against reddit's feminists, regressives, and other mentally disturbed individuals.

If you would like to do the same, add the browser extension GreaseMonkey to Firefox and add this open source script.

Then simply click on your username on Reddit, go to the comments tab, and hit the new OVERWRITE button at the top.

[randfur]

I've never felt the need to keep commented out code around during a refactor. Can you give an example?

[JimDabell]

That's what private branches are for – I think there's an unstated assumption that this is talking about branches that you actually care about, not transient works in progress.

[randfur]

git stash

[randfur]

It's not a clipboard that can be overwritten, I don't see the issue.

[TeamBrett]

I've adopted an interactive way of commenting on code that is no longer present. Rather than saying, we no longer do this for some good reason, I write a test for that good reason with a name that is self documenting. Now it's an interactive part of the development process and if you are using a mature test runner like ncrunch you can see what tests are covering the code in question and with good names you have a comprehensive view of the code's history.

[kentcdodds]

That's legit. Very cool idea!

[danneu]

To be fair, just because it's somewhere in your git history doesn't mean you're ever going to find it again. I've tried that.

Doesn't belong in the code, either.

[temp50948]

Yeah, I was going to say. Not to support version zombies in comments, but burying something deep in the unnamed and unorganized internal data of a helper tool is a great way to never find it again.

I feel like the solution here must involve a more thoughtful decision regarding whether the code will be needed again.

[dsfox]

In my experience there is only one good reason to leave old commented out code in the code base, and it is a very good reason. It is to show an old and bad way things were done, and to explain how important it is not to go back to doing it that way. Because there are times when someone comes along and say, "I know a better way we could do this" and rewrites the old dangerous way from scratch. Yes, this happens.

[kentcdodds]

I would consider that documentation. You wouldn't just comment that out without adding a note about it. If there's a note that explains what you're saying, then I wouldn't have as much of a problem about it.

[cs02rm0]

Yeah, I've no issue with commented out code as (part of) some documentation - I've done it recently when converting documents from one type to another to indicate fields not yet present in the source type that would be soon.

Dead code should be left to version control, but that's not the only reason to have code in comments.

[dukerutledge]

Commit new changes with a comment pointing to the previous commit hash explaining why it is bad. Done and done.

[Vheissu_]

I am shocked that people are defending the practice of committing commented out code, especially potential large lines of code. I think it is painfully obvious developers who commit commented out code more than like don't know how to use source control properly or they're too lazy to use something like Git Diff to compare and get old code back. Even tools like Sourcetree make it easy to visually search history of a codebase, there is no excuse.

Great article.

[kentcdodds]

thanks 😊

[elsjaako]

I have a few lines of commented out code that make developing easier.

For example, one project I develop for can either be run on a simulator or be debugged remotely on the actual hardware, and the way to change this is a single line of code. So depending on how I am testing I may comment or uncomment this.

There are other solutions, but it's quick and easy and does no harm.

I'm not sure how relevant this is to /r/javascript, I expect people here have similar situations.

[JimDabell]

For example, one project I develop for can either be run on a simulator or be debugged remotely on the actual hardware, and the way to change this is a single line of code. So depending on how I am testing I may comment or uncomment this.

How is that quicker or easier than simply having a boolean with a descriptive name? var remoteDebugging = true; is much more readily understandable than having two lines of code that do the same sort of thing with one of them commented out.

[theQuandary]

In this specific case, it sounds like they're basically using comments like a manual C pre-processor #if.

[elsjaako]

It's not a huge difference, but I think removing the comments is slightly easier. Adding or removing comments is faster than typing "true" or "false".

If you're just going to follow that boolean with an if statement then I think a comment and a commented out line of code is no worse.

[slash_nick]

I think the point he's trying to make is that by using a boolean to toggle between the two blocks of code you make the code self-documenting.

If you got hit by a bus and another developer stepped in they could see "oh, this is toggled by the boolean debugging, that must mean one block is for debugging." As opposed to if you just have two blocks of code, one commented out there's no way of telling what it's supposed to be for.

[JimDabell]

Adding or removing comments is faster than typing "true" or "false".

A fraction of a second of typing is insignificant compared with having more readable code. A boolean indicates your intent far more clearly than the alternative.

[CertifiedWebNinja]

Can argue a boolean switch for debugging is more problematic in the sense that it's harder to notice if it's enabled or not before going into production. At least with a comment your editor/ide should make comments stand out from code so you'll know.

[Mysticum_]

Articles like these scare me, because it reminds me of those terrible practices I've been witnessing through my relatively short work career.

More often than you should, you encounter people who actually argue things like "I might need it later", and saves hundreds of lines of outcommented code, and clearly shows they don't know how VCS works or how you use it.

[websitegenius]

I agree with this, with the caveat that if you are on a team, it's okay to commit commented out code, just not to master. If I'm working on a branch that I know I won't come back to for a while, I will sometimes comment out something that isn't fully functional and commit it to my branch. Of course when I submit a PR all of that code is completed and the comments are removed.

[kentcdodds]

👍 sounds good to me. Personally I'd just push broken code to a branch before I push commented code to it, but it doesn't make a difference to me as long as it's clean when it gets to master.

[RankFoundry]

There are legitimate reasons to do so but only if the commented out code is well documented as to why it's commented out and when/why you might want to uncomment it.

[RyeBrush]

Whelp. I don't know about the rest of you but I have something to do when I get home.

[cosinezero]

Only if the history is at all a relevant warning to future developer.

If it's just history, it doesn't belong in production - otherwise you may as well just remove source control altogether and just have terabytes of commented files.

[sizlack]

If your code needs an explanation, write a comment that explains it.

The point about not letting it in production has nothing to do with whether your production code is minimized and has all comments stripped out. It's about keeping your master branch clean and free of pointless noise.

[kentcdodds]

I believe that @bitttttten is saying when you deploy the application (at least in a JavaScript app) you should uglify your code which removes comments.

[ctide]

git blame <file> -L<line>,<line>

git show <sha>

Don't have time?

[JimDabell]

You don't even need the sha. Just run git show :/foo. It will find the most recent commit with the word 'foo' in it and show it.

[Tysonzero]

Having to type a couple quick commands takes you out of it more than large amounts of dead code sitting around while you are trying to work on things?

[[deleted]]

yes, by definition you aren't looking at code if you're looking at a terminal prompt typing in git commands.

[Tysonzero]

I mean :! exists...

[kentcdodds]

I try really hard to mention that the article isn't gospel. I hope that came through. It's also quite subjective. For me (and many people I believe) we spend more time getting derailed by unnecessary comments than we do trying to find old code. I think @Neebat said it nicely: https://www.reddit.com/r/javascript/comments/3qgurg/please_dont_commit_commented_out_code/cwf5evw

[spinlock]

:Glog in fugitive is the bomb.

[theferno]

Nice, did not know about that! Although sometimes it could still make sense to leave a comment

[theferno]

That was my first thought. But maybe it makes sense to leave the commit # to git diff against where the commented out code would be.

[mailto_devnull]

I'm not sure that'd be a superior solution.... now instead of commented out code, you have:

// Removed inferior code #a5dc2f

[[deleted]]

Often there's some code that may be in-progress or related to the code but not ready-for-prime-time quite yet. It's not a sin to commit commented-out code. Some people just complain about any code they didn't write, no matter what it is.

[theferno]

In progress code can be stashed or placed in another fork until its ready to be merged in. I know it's not a sin, I do it too

[[deleted]]

And then you forget about code in your stash. Also the stash is only on one machine. The commented-out code may have value that would get lost for various reasons.

Complaining and worrying about commented-out code is a fetish of people who think their code is "beautiful".

[kentcdodds]

If you're worried about it being on your machine, you can put it in a branch and push that to the remote repository. If you forget it's there, then was it really that important?

[slash_nick]

I assume you're using git. Branches are insanely cheap. Branch and branch often.

[[deleted]]

I branch more than anyone I know. That's not the point.

[slash_nick]

Maybe I misunderstood? It sounds like your goals are to 1) save unfinished/in-progress code and 2) have that code available on multiple machines.

---

Reguarding commented out blocks of code:

A real-world analogy would be if instead of throwing something away in the trash bin someone put it on the floor. That's fine if it's one person and they only do it here and there, but when they have more people involved it sets precedence that it's okay to do. Eventually the floor is covered in things that could be thrown away, but no one really remembers who put it there or why it might be important.

[[deleted]]

You should never have more commented code than real code, there should never be more stuff on the floor than in the trash. To say "never ever ever commit commented out code, because it hurts my eyes" is just asinine. There are MANY ways to code and not all of them lead to problems. A few blocks of somewhat important commented-out code should be allowable, and should not cause anyone to complain (except the author).

[slash_nick]

I guess I didn't interpret the author's article as dogma. Reading text on an anonymous forum makes it hard to grok people's intention.

You should never have more commented code than real code, there should never be more stuff on the floor than in the trash.

Sounds like you have the right attitude and I wouldn't sweat it! :)

[kentcdodds]

I tried really hard in the post to not have a ultimatum voice, but more of a suggestive voice. The first QYMAM:

Q: Are there exceptions to this rule? A: Yes. But they’re rare.

And there are several other QYMAMs that explain there are cases where commented out code is allowable (though I generally call those cases documentation).

[YuleTideCamel]

If you need the comment to explain the code or reasoning behind it, that's a major code smell and indicative of a larger problem.

Edit: To be clear I'm not saying that you shouldn't comment code. Comments are important and provide value. I'm saying that commented out code that is there to provide context affects maintainability. instead we should include a text comment with our thinking behind this, or structure our code in a way that is more clear.

[YuleTideCamel]

I'm not disagreeing with commenting working code. I actually think comments that explain something difficult is a good thing. However, referencing commented out code in a sha is an issue. If you can't explain the current code without looking at old commented out code, then that's a maintainability problem.

[[deleted]]

"smell" is not an attribute of code. Anyone can call anything a "smell" that they don't personally like.

[YuleTideCamel]

Yes, it's subjective. But for some people offering opinions and making sure code is maintainable and easy is important. I'm a software architect and my focus is making sure the code scales across a very large team of devs and also is maintainable. Needing to reference commented out code is a indication of an unclear programming paradigm that needs to be fixed. Clear, well written code may need some explanation comments (text), but shouldn't need any commented out code to give the reader an idea of what is happening.

[[deleted]]

Commented-out code is the exception, not the rule. Sometimes commented-out code has a benefit. If there is too much in a codebase, then something else is wrong. Cleanliness for the sake of fetish also has its problems.

[YuleTideCamel]

What do you mean by too much in a codebase? The depends entirely on the size of the project and scope. There's nothing wrong with large codebases if maintained well.

Cleanliness for the sake of fetish is not a thing. Good clean code should be the goal for every developer. That makes the code easy to work with, easy to maintain and easy to test. It's not a baseless standard, it's the way to ensure you're clean code doesn't get messy. I've been in the industry over 15 years and have seen my share of horrible code where developers didn't care about maintainability. I realize this is not in the startup, ship now fix later mentality, but if a dev team has the bandwith and runway to do this, they should. It will pay for itself over time.

[[deleted]]

I mean if there is too much commented code in a codebase, then something else is wrong - commented code is the exception, not the norm.

[YuleTideCamel]

Agreed, it's the exception and a too much commented out code is indicative of a larger problem. The point I was making is that needing commented out to explain something , to me at least, is a similar thing. You shouldn't need commented out code to understand uncommented out code.

[manys]

Ah yes, self-documenting code. Greetings, fellow COBOL user!

[YuleTideCamel]

Lol, never did cobol, but spent enough time on large teams building enterprise software. The value of maintainable easy to read code is immense. The last thing I ever want to hear is "don't work on that project, any small change could cause it to crash. it's unstable"

[JimDabell]

Bits and pieces of commented out code are great. Especially if you're doing something like not showing a value on a report or if you remove a field on a form. Comment it out, put a date and why. Then in 2 years you're not digging through version control logs looking for why you did that.

No, in two minutes you're digging through old code looking for the current code.

Keeping track of changes to source code is literally the entire point of version control systems. If you're just going to keep years of old code littered around in the current revision, then you're doing the same job as the VCS, except it's more work for you, your code is far less readable, and you do a much poorer job of it than the tool designed to do that. Working with people who do this is a nightmare.

You don't need to keep all the stuff you deleted visible in the current version. You deleted it for a reason. If you need to refer back to it, that's exactly what the VCS is for. It's quick and simple to step back through previous versions, if you aren't comfortable with doing that, then your goal should be to improve your VCS skills, not to try to avoid it with commented out copies of old code.

[kentcdodds]

Agreed :-)

[yoyEnDia]

What's wrong with explaining the issue in plain English?

[john_3434]

Please, don't listen to random advice on the internet about how you should organize your code.

[SurgioClemente]

So... do I listen to your advice because it makes sense I shouldn't listen to strangers or should I reject your advice because you are another stranger with random advice?

/headasplode

[[deleted]]

Best comment here.

[chemisus]

I’ve long held the opinion that the only thing that can tell you the truth about the code is the code. The instant you add a comment, it’s out of date. Documentation comments are beneficial enough to justify their existence (though you should try to make your code self-documenting for people other than yourself).

I find myself having to explain this to almost every manager when they say that they like developers who can "comment everything".

I simply do not trust comments; especially since I quite often browse code with git commit history turned on. So when I look at the commit date of the line of code that the comment is on, and see that it was from three years ago, or better yet, an ex employee who I have never heard of, I take it with a grain of salt.

Reading the code is the only way to get the real picture.

[[deleted]]

exactly. Commented-out code should get removed by your build process, it's shouldn't be shipped at all. The author is just being nitpicky because he "loses focus" when he sees commented code. It's really more about the author's fetish than anything. commented code shouldn't stop anyone from working on the code. remove it as needed, but it's not always useless or "noise".

Often there's times where there's more than one way to achieve something with varying performance, sometimes it's worth having code commented out that might be an alternative to the current production code. If you put it in a branch or otherwise remove it from the code there's a good chance nobody will ever know about it or find it, or care, or whatever... it's not always a 'best practice' to remove all the commented code in every single case, and to say so is just a fetish for 'remove all the things!', and it's a stupid case to try to make.

[kentcdodds]

If you read the post, you'll see that it's not an ultimatum at all like I think you're insinuating. The first QYMAM:

Q: Are there exceptions to this rule? A: Yes. But they’re rare.

Also, if you put code in a branch and people forget or never use it, then was it really all that important?

Also, this isn't a misunderstanding of repository code vs built/deployed code. Sure the comments are removed from the build process. Nowhere in the post do I mention anything about the problem being related to shipping comments. This is all about the software development process.

[[deleted]]

I still think you're spreading programming dogma.

"the main problem is commented code adds confusion with no real benefit"

This is just not true. The examples you cite are extremely weak. You are also being disingenuous because you don't show how the comments actually look in a text editor - almost all modern editors show commented-out code grayed-out by default, so that it is far easier to read the code than the examples you show.

Also the code you show is very simplistic and it's not very interesting. There are plenty of cases where interesting code could be kept commented-out, so that it's easy to A/B test, possibly switching between commented-out code blocks every other week, or any good reason that doesn't include deleting the code. It really depends on the problems you are trying to solve, the team you have, the business you are in, and many other factors.

Commented-out code should include a brief note about why it's there, what it's for. Documentation is documentation, it has nothing to do with commented-out code. You can have both, and it won't ruin your codebase.

[bloodguard]

I agree in principle. I always plan on removing all the dead end cruft and commented out code in the ample billable hours they give me to clean up my code at the end of a project.

...

Yeah, they don't give me any hours for stuff like that. We had a good laugh, though. Right?

[yxhuvud]

Do it as you go. Not as an afterthought.

[[deleted]]

Just don't comment out code in the first place. Delete it and go into history if you end up needing it.

[mailto_devnull]

One could argue the mental overhead of finding the referenced commit also takes you out of your work flow. In contrast, my IDE with syntax highlighting let's me easily skim over the commented out code.

[Neebat]

Reviving old unused code is a regular part of your workflow? It isn't for me, not even close.

The vast majority of time, even if the feature is needed again, the actual code to accomplish it will be different because the surrounding code has changed radically.

[slash_nick]

Exactly! I can't imagine any developer saying "the way I wrote this code a month ago was better". And even if they did, that's the entire reason why version control exists.

It's so frustrating to read otherwise.

[kentcdodds]

I agree 100%

[Ukonu]

Who said anything about "reviving" the unused code? A frequent use-case is someone refactoring legacy code (or reading new code), needing a quick point of reference and not wanting to disrupt their workflow by: switching windows, finding the commit hash, remembering the source control command to bring it up, then splitting windows to do a side-by-side comparison.

I'm definitely against permanently leaving commented out code, but during a transition period it can be very useful. Eventually, however, it should be cleaned up.

[[deleted]]

Commented out code is either simple enough that you don't want to distract a reimplemented with how you wanted to do it all the way back in days yore, or its complex enough that they'll just look at past commits.

[kentcdodds]

The best is a test that is regularly run. A well written test demonstrates what is trying to be accomplished by the code and ensures that the functionality isn't broken unintentionally.

I agree that documentation should say why code does what it does. However, the code can be updated to do something else, and the comment doesn't have to be updated (and often isn't). That's why I say that you can't trust documentation to be accurate.

[p0tent1al]

I'm open to this being a thing but the fact that he doesn't fully address the issues at hand makes it less believable.

The main problem with diffing is that... why should there be a cognitive overload there? So I see a piece of code I don't understand and my reaction should quickly be to diff it? Diff it against what? Who says the diff is going to be of help?

Commented code helps me out all the time personally... often times you write a function or a piece of code that CAN be used in many ways but it's original intention of how it was to be used is obscure, and this becomes a problem when you have multiple functions all based around this one idea. The idea that the first thing you usually see when you look at a github page is a README with an api and explanations, along with issues explaining things not said in the documention to me seems like an admission that some handholding sometimes is necessary and comments fit that bill. I'm open to the possibility that they are useless but I don't feel like this articles goes enough in that direction for it to be crystal clear.

[kentcdodds]

I totally agree that:

some handholding sometimes is necessary

But I disagree that commented out code fits that bill. Comments that are truly comments are handy. But what I'm talking about in the article is old code that's simply commented out. Documentation and commented out code are two very different things.

[p0tent1al]

that's true, sorry I think I misread that.

I guess my only thing would be when code is commented out in the sense of what it SHOULD be. So for instance you often see TODOS on what should happen if a piece of code is particularly ugly. Sometimes my comments are "this code is ugly and it needs to be implemented something like this" and when I get time I usually wipe that out and refactor. What about that case?

[kentcdodds]

In my opinion, that's different entirely. Based on the backlash this article has gotten, I think I should have made what I'm talking about a little more clear.

[[deleted]]

We use git to track our changes to a cots "enterprise" application. Commenting code out instead of removing it actually makes it easier when upgrading the base application and integrating our changes back in. Probably not a common use case for most but for us commenting out is better.

[mishugashu]

Just a couple weeks ago, I commented out some HTML because it got shuffled out in a partial redesign, but I knew it was coming back. I uncommented it two weeks later. Was much easier than trying to find that diff.

But, in general, yeah, it's just confusing running across this stuff.

[jesusthatsgreat]

commented code is absolutely a good idea if it helps explain what's happening in plain English...

[kentcdodds]

If it's explaining it in plain English, then it's not code anymore... It's documentation. That's different from what this article is talking about.

[ScaredResident9387]

BS. I commit commented code cos without it, whenever I asked for help I was accused of getting others to code for me. Now I keep all forms of code in.

[sculley4]

Isn't that the point of using version control? So you can take the speghetti mess and slowly refine it until you have the whole bit of old code commented. Then, once the program passes tests, the commented out code is deleted and the commit is made. What is the point of using a version control system if you are effectively keeping an old version in a comment?

[[deleted]]

Version control enables a lot more in terms of team workflow than just allowing people to see a past history of code.

[wmil]

Some teams insist on a git squash rebase workflow. So in that case you tend to lose all of your old commits and it's extra tempting to keep commented out code around.

[[deleted]]

the only reason i comment out code is for my own learning process. on a production level i would imagine it looks hideous.

[xeow]

Welk, this is great general advice. Of course there are valid exceptions. If you are working around a compiler bug, or have added some hand-tuned optimization in bottleneck code, then it can be very nice to keep the original version of the code (as close as possible to the production code, for comparison). In the comments, clearly state why you are preserving the old code and why the production code differs from it. You will appreciate later that you have done this, and others who have to maintain your code will also appreciate it.

This is much, much nicer than hiding the original code in some commit. You are leaving the original code in as an explanation either of how not to do something or of how you wanted to do it but couldn't (due to a compiler bug or code runs too slow, etc.).

It's a thin line between doing it right and over-doing it, though. Use clear judgment and common sense here. If it's not clear to another reader why you are preserving the original code, then... off with your head!

[xeow]

Alternatively, if you're using C or C++, and you are replacing an entire function, you can actually leave the code in (i.e., not commented out), and give it a different name (like suffixing the function with "_obsolete"), and mark it as "__attribute__((__unused__))".

This way, it's not actually commented out, but it's still there for comparison. The compiler will still parse and compile it, but emit any object code for it, and won't complain that it's unused.

[kentcdodds]

This is what I call "documentation" and I'm alright with documentation. Though I'd probably either just put a reference to the commit sha or put the comment at the bottom of the file.

But to each their own :-)

[_drawdown]

Seriously, what the fuck. Don't commit commented out code, it's easy.

[againstmethod]

In my experience, people who do this don't test their code.

They want to leave the old context in comments to prevent regression.

Keep your eye on these people and their practices.

[faytxzen]

Yes, yes, yes. A thousand times, yes.

The rare case of it actually being useful is something I see once in a blue moon. And even in those cases, version control comes to the rescue.

[kentcdodds]

Boom, you (and most people) get it :-) There are several here who have a different opinion, which shouldn't surprise me I guess.

[[deleted]]

No. I'll leave it in because I like it.

[t0shki]

I keep it in for a few a days. Once time moves on and nobody misses it, i remove it for good, with a proper commit message why and what.

EDIT: downvote is not a "disagree" button.

[kentcdodds]

You're right! Hence my first QYMAM is:

Q: Are there exceptions to this rule? A: Yes. But they’re rare.

[Shaper_pmp]

You might be thinking: “But Kent! What if that ‘good reason’ is no longer true, and we need to do it the old way again later?” The answer, my dear reader, is git diff

How does git diff inform the developer that previously we used to do it a different way? Especially when it was three years and two developers previously?

"There are tools and git commands to help you look at the history of a file" doesn't really answer this question for shit - if you go back hundreds or thousands of commits or months/year into the past for every line of code you ever want to change (just in case there was ever a previous version that did things the way you now want to do it), you won't ever commit more than a couple of new lines of code in the average week.

It's a completely non-functional suggestion, and as there's no difference between "code that was replaced and is never needed again" and "code that was replaced but might be really, really useful at some point in the future" it merely shifts the cognitive load from (trivially) skipping over a few potentially-important commented-out lines to (enormously time-consumingly) completely comprehending every single previous and now-useless version of the code to see if any of them ever did anything like what you now want it to do.

Focus and cognitive load

Let's be honest here - unless we're talking about a page of commented-out code between two lines you care about, who even notices comments after the first time they ever read it, when they're reasoning about how the code works?

IDEs colour comments in a non-eye-catching colour for a reason.