7 ms·

Committing commented out code means you don't know how to use your version control system. A comment with hash of the commit of the old code, or a command to sh

Committing commented out code means you don't know how to use your version control system. A comment with hash of the commit of the old code, or a command to show an older version of the file using your vcs system, is much better, and more team-friendly.

lqdc13 11y ago
Sure but then you switch Version Control systems later and the hash/vcs command may not mean anything.
- nailer 11y ago
  I wasn't around when rcs was a thing, but cvs to svn and svn to git preserved history.
  - revelation 11y ago
    It will automagically scan through all files and replace what looks like a revision number with the correct git hash?
    - asdfaoeu 11y ago
      I don't know about the cvs to svn migration but migrating from git to svn you generally can keep the original svn commit numbers in the history such that you can look up svn revision numbers like that.
      - jheriko 11y ago
        he means replacing comments mentioning revision numbers. no source control migration does this - it would be harmful if done unchecked (revision numbers like 1 will turn into compile errors or very confused comments in the most naive implementation, for example)
- LukeShu 11y ago
  Exactly. Emacs has changed VCS at least 4 times since the code was commented out. (pre-RCS (no VCS?) -> RCS -> CVS -> bzr -> git) I've had codebases with references to bug IDs... from 3 bug trackers ago.
  - LukeShu 11y ago
    I can't seem to edit the comment, but: change that to 5 times, they used Arch between CVS and bzr.
- weinzierl 11y ago
  With a capable vcs you don't need a version number, hash or other id. These things are always fragile. Just add a comment saying that this is a rewrite of the old part the code and document any intended functional differences. You can then search through the history for the first appearance of that specific comment. With git this is done with the pickaxe command.
  - shawn-furyan 11y ago
    I think the issue here is that as nice as you might find your VCS tools when you write code, the code you are writing, particularly on code bases that are already old, may survive significantly longer than the current hot VCS. If the entire commit history gets squashed when the code base is ported over to a new VCS, then VCS history may not be robust enough to communicate with maintainers in the distant future (that is, potentially a decade or less from now given the typical half life of these sort of tools).
    - kalleboo 11y ago
      I don't blame the devs 30 years ago for being cautious but now emacs has survived 5(?) VCS migrations with all the data intact, the tools are more mature now and it shouldn't be a worry anymore.
- shawn-furyan 11y ago
  Perhaps what we need are reliable tools that will robustly port commits forward from old VCSs to new ones. Does something like that exist? The most common defense of this code seems to stem from a vague sense that VCS history is more ephemeral than committed code. With proper tooling (or better awareness of the appropriate tools if they do in fact exist), this anxiety could potentially be allayed.
  - telotortium 11y ago
    Eric S. Raymond wrote a tool called reposurgeon[0] for just this purpose. Coincidentally, he used it to migrate Emacs to Git and clean up the repo, although I'm not sure how much manual work he had to do to besides running reposurgeon. [0] http://www.catb.org/esr/reposurgeon/ http://www.catb.org/esr/reposurgeon/ [1] http://esr.ibiblio.org/?p=6524 http://esr.ibiblio.org/?p=6524
codemac 11y ago
Committing commented out code means you're trying to communicate with comments in your code. English isn't the only language that's useful in comments, especially when trying to document something of computable logic. If you have any comments in your code at all, you could make the same argument about "not knowing how to use your version control system" as everything could be in commit logs. And please define "team-friendly", it is absurd to suggest that the git cli makes anything friendly.
- pyre 11y ago
  > And please define "team-friendly", it is absurd to suggest that the git cli makes anything friendly. Is this how you develop? 1. Comment out old code. Make a note of why this was removed (and maybe the date). 2. Add new code. 3. Commit.
  - hobs 11y ago
    I have seen that. I have also seen that, but without the third step. Its the fastest way to get a bunch of comments in your code(as well as code) that is probably meaningless if not actively bad for you to store in your brain.
  - codemac 11y ago
    Is this how you document your code? 1. Write comment about code, and commit it. 2. Delete comment about code, and commit the removal. I mean hey - your team mates should be able to use a VCS right? Facetious workflows miss the point, judgment can be used to determine what should be commented out vs not. I strongly prefer source code that is well documented, not at some point in the past, but right there at HEAD/master/main/tip/whatever
    - pyre 11y ago
      While that might be true, keeping an old reference implementation around for 30+ years "just in case" you hit some aberrant behaviour or weird edge-case seems extreme. It seems to me (and I may be wrong) that it would make more sense to either turn the reference implementation into a spec document (and keep that next to the code) or to dub that code the "canonical reference implementation" instead of referencing some ancient version of Emacs. By referencing the ancient version of Emacs (and the subsequent change to the new code), the comment comes across as an anachronism. It was (seemingly) left there in case there were compatibility issues while moving to the new code. This seems out of place now because if compatibility issues haven't come up in 30+ years, then I doubt that they will now (or that there is much code relying on edge-case quirks from such ancient versions of Emacs). At what point does the current implementation (and any quirks that deviate from that ancient version) become the reference implementation? In another 30 years?
incepted 11y ago
> Committing commented out code means you don't know how to use your version control system. Read the linked article more carefully. It's an example of how, sometimes, it's better to keep comments in the code than relying on source control to preserve them. These situations are rare, but they happen. People who say "Commented code should always be deleted, period" need to be a bit more open minded about the constraints in which we operate in the real world.
- V-2 11y ago
  I don't rule out there may be cases when something like that is justified, but burden of proof lies on the other party, and having read most comments I remain unconvinced. The "close-minded" crowd is making more sense to me. Of course people will go to great lengths to justify cutting corners, shortcuts, messiness etc. it's always called for by exceptional circumstances :) I just hope my doctor isn't open-minded about washing his hands...
0x0 11y ago
Respectfully disagree. If it's not "in your face", you'll forget it's there - or even never have known about it, if you weren't on the project since the beginning. Also, it won't show up in simple greps. Not saying you should leave every old method around, but for some routines (or part of routines) it can be very instructive to surface what DIDN'T work.
logicallee 11y ago
And including ANY comment in code - as in, mixing code and comments in the same file - means that your workflow doesn't support external documentation keyed to branches, hashes, filenames, and line numbers. Likewise, naming variables, functions, classes, and continuously typing out the same name over and over again means that your language and IDE is not rich enough to contain pronouns, making you have to type tediously instead of something even sightly more natural. Why don't we improve languages so that they have pronouns for the stuff you're doing right there? Why don't comments get linked to line numbers in some external layer? And why would anyone commit commnented-out code to a repository? The only answer to all of the above is that we are living in 2015 and not some future year. you work with what you have.
- imtringued 11y ago
  We have those "tedious" things because programmers don't like ambiguity.
- dTal 11y ago
  >Why don't we improve languages so that they have pronouns for the stuff you're doing right there? Interestingly, we do sort of have that - in most CAS interfaces "Ans" can be used to refer to the last calculated value. A lot of programming REPLs can do this sort of thing too. Another example might perhaps be Bash's $1, $2, $3 etc for positional arguments.
overgard 11y ago
You might notice the commented code mentions CVS -- even though it's now on git. If they had done what you're suggesting, it would almost assuredly lead to a dead-end for someone trying to look up the code.

lqdc13 11y ago

Sure but then you switch Version Control systems later and the hash/vcs command may not mean anything.

nailer 11y ago
I wasn't around when rcs was a thing, but cvs to svn and svn to git preserved history.
- revelation 11y ago
  It will automagically scan through all files and replace what looks like a revision number with the correct git hash?
  - asdfaoeu 11y ago
    I don't know about the cvs to svn migration but migrating from git to svn you generally can keep the original svn commit numbers in the history such that you can look up svn revision numbers like that.
    - jheriko 11y ago
      he means replacing comments mentioning revision numbers. no source control migration does this - it would be harmful if done unchecked (revision numbers like 1 will turn into compile errors or very confused comments in the most naive implementation, for example)
LukeShu 11y ago
Exactly. Emacs has changed VCS at least 4 times since the code was commented out. (pre-RCS (no VCS?) -> RCS -> CVS -> bzr -> git) I've had codebases with references to bug IDs... from 3 bug trackers ago.
- LukeShu 11y ago
  I can't seem to edit the comment, but: change that to 5 times, they used Arch between CVS and bzr.
weinzierl 11y ago
With a capable vcs you don't need a version number, hash or other id. These things are always fragile. Just add a comment saying that this is a rewrite of the old part the code and document any intended functional differences. You can then search through the history for the first appearance of that specific comment. With git this is done with the pickaxe command.
- shawn-furyan 11y ago
  I think the issue here is that as nice as you might find your VCS tools when you write code, the code you are writing, particularly on code bases that are already old, may survive significantly longer than the current hot VCS. If the entire commit history gets squashed when the code base is ported over to a new VCS, then VCS history may not be robust enough to communicate with maintainers in the distant future (that is, potentially a decade or less from now given the typical half life of these sort of tools).
  - kalleboo 11y ago
    I don't blame the devs 30 years ago for being cautious but now emacs has survived 5(?) VCS migrations with all the data intact, the tools are more mature now and it shouldn't be a worry anymore.
shawn-furyan 11y ago
Perhaps what we need are reliable tools that will robustly port commits forward from old VCSs to new ones. Does something like that exist? The most common defense of this code seems to stem from a vague sense that VCS history is more ephemeral than committed code. With proper tooling (or better awareness of the appropriate tools if they do in fact exist), this anxiety could potentially be allayed.
- telotortium 11y ago
  Eric S. Raymond wrote a tool called reposurgeon[0] for just this purpose. Coincidentally, he used it to migrate Emacs to Git and clean up the repo, although I'm not sure how much manual work he had to do to besides running reposurgeon. [0] http://www.catb.org/esr/reposurgeon/ http://www.catb.org/esr/reposurgeon/ [1] http://esr.ibiblio.org/?p=6524 http://esr.ibiblio.org/?p=6524

codemac 11y ago

Committing commented out code means you're trying to communicate with comments in your code. English isn't the only language that's useful in comments, especially when trying to document something of computable logic. If you have any comments in your code at all, you could make the same argument about "not knowing how to use your version control system" as everything could be in commit logs. And please define "team-friendly", it is absurd to suggest that the git cli makes anything friendly.

pyre 11y ago
> And please define "team-friendly", it is absurd to suggest that the git cli makes anything friendly. Is this how you develop? 1. Comment out old code. Make a note of why this was removed (and maybe the date). 2. Add new code. 3. Commit.
- hobs 11y ago
  I have seen that. I have also seen that, but without the third step. Its the fastest way to get a bunch of comments in your code(as well as code) that is probably meaningless if not actively bad for you to store in your brain.
- codemac 11y ago
  Is this how you document your code? 1. Write comment about code, and commit it. 2. Delete comment about code, and commit the removal. I mean hey - your team mates should be able to use a VCS right? Facetious workflows miss the point, judgment can be used to determine what should be commented out vs not. I strongly prefer source code that is well documented, not at some point in the past, but right there at HEAD/master/main/tip/whatever
  - pyre 11y ago
    While that might be true, keeping an old reference implementation around for 30+ years "just in case" you hit some aberrant behaviour or weird edge-case seems extreme. It seems to me (and I may be wrong) that it would make more sense to either turn the reference implementation into a spec document (and keep that next to the code) or to dub that code the "canonical reference implementation" instead of referencing some ancient version of Emacs. By referencing the ancient version of Emacs (and the subsequent change to the new code), the comment comes across as an anachronism. It was (seemingly) left there in case there were compatibility issues while moving to the new code. This seems out of place now because if compatibility issues haven't come up in 30+ years, then I doubt that they will now (or that there is much code relying on edge-case quirks from such ancient versions of Emacs). At what point does the current implementation (and any quirks that deviate from that ancient version) become the reference implementation? In another 30 years?

incepted 11y ago

> Committing commented out code means you don't know how to use your version control system. Read the linked article more carefully. It's an example of how, sometimes, it's better to keep comments in the code than relying on source control to preserve them. These situations are rare, but they happen. People who say "Commented code should always be deleted, period" need to be a bit more open minded about the constraints in which we operate in the real world.

V-2 11y ago
I don't rule out there may be cases when something like that is justified, but burden of proof lies on the other party, and having read most comments I remain unconvinced. The "close-minded" crowd is making more sense to me. Of course people will go to great lengths to justify cutting corners, shortcuts, messiness etc. it's always called for by exceptional circumstances :) I just hope my doctor isn't open-minded about washing his hands...

0x0 11y ago

Respectfully disagree. If it's not "in your face", you'll forget it's there - or even never have known about it, if you weren't on the project since the beginning. Also, it won't show up in simple greps. Not saying you should leave every old method around, but for some routines (or part of routines) it can be very instructive to surface what DIDN'T work.

logicallee 11y ago

And including ANY comment in code - as in, mixing code and comments in the same file - means that your workflow doesn't support external documentation keyed to branches, hashes, filenames, and line numbers. Likewise, naming variables, functions, classes, and continuously typing out the same name over and over again means that your language and IDE is not rich enough to contain pronouns, making you have to type tediously instead of something even sightly more natural. Why don't we improve languages so that they have pronouns for the stuff you're doing right there? Why don't comments get linked to line numbers in some external layer? And why would anyone commit commnented-out code to a repository? The only answer to all of the above is that we are living in 2015 and not some future year. you work with what you have.

imtringued 11y ago
We have those "tedious" things because programmers don't like ambiguity.
dTal 11y ago
>Why don't we improve languages so that they have pronouns for the stuff you're doing right there? Interestingly, we do sort of have that - in most CAS interfaces "Ans" can be used to refer to the last calculated value. A lot of programming REPLs can do this sort of thing too. Another example might perhaps be Bash's $1, $2, $3 etc for positional arguments.

overgard 11y ago

You might notice the commented code mentions CVS -- even though it's now on git. If they had done what you're suggesting, it would almost assuredly lead to a dead-end for someone trying to look up the code.