Ask HN: Do you keep wrong code in a comment as a reminder of what doesn't work? | Hacker News Reader

Ask HN: Do you keep wrong code in a comment as a reminder of what doesn't work?

10 pointsamichail16 comments

For example, if an assertion is no longer true, do you keep it in a comment as a reminder of what isn't true?

Or if an algorithm is wrong, do you keep it in a comment as a reminder and perhaps explain why it doesn't work?

Only if it doesn't waste space AND holds a lesson that may still be of use to the project.

I tend to like code to be structured in a way that allows maximal contextual readability (as in: a glance at a page of code should allow to see enough context to understand what's going on)… and that requires to keep any of the clutter that tends to stretch the code too much vertically to a minimum.

So: if it's just a short line so that it fits as an inline comment right side of the corrected version AND holds some lesson that may be of use again, I keep it like that. If it's too long, I just put a succint ref to the problem as an inline comment to the corrected version and move the old code to be replaced into a separate markdown file together with a short explanation of the problem. And if the info of the old version clearly isn't gonna be of any use again, I consider the version control system to be the place for it, not the code either.

I often keep commented out wrong code with an explanation of what is wrong with it in the comment. But most of the code I've written is experimental, often involving reverse engineering black box systems so they can be used in unconventional ways for research purposes. So that commented code is a series of clues into the hidden state of the black box and thus are important for gaining further understanding. Once I've figured out the puzzle then I decide whether it's important to keep those comments. If the code is passed on to someone else I'll often delete the comments, though I may copy them to a wiki for my own reference. If I'm the only one working on it I like to keep the comments unless they start making the code unwieldy and difficult to work with. I do replace the commented out code with a detailed description of my understanding of how things work, often quite extensive comments. I've had to work with too much code written by other people that is impenetrable because they didn't describe the codes purpose which makes making changes difficult. Keeping code "clean looking" is ridiculous in my opinion when the goal should be keeping the code maintainable.

I personally do not - if something seems like it might work but doesn't I'll leave a comment in words explaining why I didn't do it that way, but I pretty much never leave wrong code commented out.

No. I don't want to find commented out code when searching the code base. I might leave a prose comment explaining what didn't work to prevent someone implementing the same mistake in the future.

I would prefer to keep this information in version control. A commit message with a thorough explanation of why the previous version failed and how the change resolves the problem would accomplish the same thing as a comment in the code, but it wouldn't clutter the correct version.

And as others have said, you could add some unit tests to prevent others (or your future self) from creating a regression.

It might be more prudent to write some unit tests to enforce the desired behavior, in particular any edge cases the current solution supports that past solutions didn’t support.

Then when working on refactoring you have the tests as a reminder of what cases need to be supported.

It really depends on the circumstance.

Generally the code should be correct and work as current requirements dictate. So probably you don't want to keep an entire section of the old code just commented out and sitting there.

What I've seen done as a practice is to leave a brief comment referencing specific commit hashes in cases where an important change to business logic is involved.

Most of the time this shouldn't be necessary though. In the course of investigating bugs, going through the commit history should provide most of the information needed. Do a "git blame" and read the notes the previous person left in their commit messages.

Not long-term, no. Quite often I'll have bits of code commented out while I'm making changes or debugging issues, but I'll make sure that they're removed before I commit the code.

While I remove the old code, I do sometimes leave a comment explaining why the new code is there, e.g.

    # Using a heap sort here as we keep getting data in a order that is pathological for quick sort

Verbose comments are useful, but this is why you keep your code in a version control system, and why you get good at going through the code's history, and why commit messages and diffs matter.

Someone opening the file should get as little as they need to be effective at their job/ticket. Sometimes that means they need extensive history of how we got here, but probably not.

I would retain one or two line changes with a comment if it was a fix for a hard to reproduce / corner scenario. Typically with embedded programming it helps- as some fixes are chipset or hardware version specific

Otherwise, just clear off wrong code without much comment. I've seen cases where comments too get bloated up over the years and no body owns to clear it up

No that seems kinda odd. However, if I were to make what seems like an unusual decision, I would include a comment explaining the rationale.

Like "SSL is disabled here due to compatibility issues with system XYZ, <link to docs>"

I sometimes keep old code in the comments just to understand what went wrong if I wrote it correctly. Once I get closer to a "release", I do delete irrelevant comments to keep the code cleaner.

Never. Comments should clarify what code does or why it does what it does. Nothing else.

Mostly not, it's not scalable.

I'd rather keep a test than a comment.

Reply on news.ycombinator.com