I've used a different way of commenting out code in the past. First, I use a header (a .ReadMe method in a form/class)

* /01  Date  WhoMadeMod
*    a. Description of mod
*    b. Description of mod
* /02  Date  WhoMadeMod

Then to comment out a line in the code:

*/01-a

It provided a trail back to not only what was commented, but why. Then when doing maintenance on a file, I would prune out anything older than a year.

Now with good source control and compare programs, I don't do this. Once I have new code in place and working, I delete the old code.

Robert Martin also talks about commenting out lines in Clean Code.




>In VFP, I do exactly what Craig doesn't like but only in general sections, not for each code block:
>
>

>*--TCHolzer 08/19/2009 BEGIN Issue # 12345 Fix this or that 
>*!* original code commented out
>new code here
>...
>*--TCHolzer 08/19/2009 END Issue # 12345 Fix this or that 
>
>or general:
>
>*--Explain what the purpose of this section is
>
>etc...
>

>
>however, it is more functional, not specific to what each code block does, because that should be evident to a programmer who knows VFP
>
>in dotnet, we use xml comments for functional sections as well so the developer who comes along later understands the 'purpose' of the code. We don't add specific comments for every single thing because any developer who understands that language should get that immediately.