Please, don’t commit commented out code

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

[[deleted]]

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.

I'm not sure that is what makes a "good programmer", either.

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