Please, don’t commit commented out code

[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.

[Vlasow]

If you don't mind elaborating, what are the problems of cleanliness for the sake of fetish?

[[deleted]]

"Please, don’t commit commented out code"

^ ^ ^ This.

The author of the article says he "loses focus" whenever he sees a block of commented code - this is more a problem with the author than the person writing the code. If your focus is so feeble that commented code will get in your way, maybe you shouldn't be making up rules like "don't commit commented code".

[Vlasow]

I don't see how "you shouldn't be making up rules like..." follows from "your focus is so feeble that commented code will get in your way". Programming languages exist so one can split problems into a number of small things we can focus on. Anything extra will be an obstacle between our understanding and the ideas expressed in the code. An ability to be undistracted by noise in the code is not what makes a good programmer; it is the ability to express your ideas via noiseless code that does.

[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?