h2g2 The Hitchhiker's Guide to the Galaxy: Earth Edition

The bit about lots of comments is good advice, BUT you must remember to update the comments when you change the code. If you don't, the comments will get out of step with the code and will be of no use to anybody, no matter how appropriate the comments were in the first place. I've worked at more than one place where software documentation was poor, to say the least. The attitude of the Chief Software Designer (sic) at one company was, 'The documentation's in the code', meaning that the comments in the software were the documentation. However, the comments dated back to when the code was first written, and the code had been changed umpteen times without the comments being changed. Consequently the comments bore no relation to what the code was doing!

Indeed.

Also, when you want to remove some code, for goodness sake don't just comment it out. If you do then some time in the future someone investigating a bug will just uncomment the code without thinking about what it does...always happens eventually.

Sometimes it's good to comment out code. If you're making a temporary change or if you're not entirely sure your changes will work. That makes it easier to revert to the previous processing. It's also a way of keeping track of attempted fixes: "Well, this didn't work, maybe I'll try... oops, nope, I already tried that, there's the old code."

It can cause problems, but it can also be useful. I wouldn't say absolutely always or absolutely never to commenting out old code.

A decent delta-based source code management system, such as PVCS or SourceSafe is a better way to undo changes if they didn't work.

I've also found it very helpful to have the documentation 'signed'. Leaving your name in with whatever documentation you write (particularly when you're documenting a change or bug fix) will let other programmers know who to talk to when they encounter the code change and want to know the details, the who and the why, regarding the change.

It seems very appropriate that someone on this forum (based of course around a humourous work of fiction) should call SourceSafe a decent source control system.

One company I worked for (who shall best remain nameless) kept each source file on a floppy disk and you could only work on that file if you had the floppy in your PC.
SourceSafe has faults, but it's better than that