A Conversation for Seven Secrets of Successful Programmers

More on comments

Post 1

Cheerful Dragon

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!

More on comments

Post 2

Is mise Duncan


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.

More on comments

Post 3


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.

More on comments

Post 4

Is mise Duncan

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.

More on comments

Post 5


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.


Post 6

Researcher 175611

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.


Post 7

Is mise Duncan

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

Key: Complain about this post

Write an Entry

"The Hitchhiker's Guide to the Galaxy is a wholly remarkable book. It has been compiled and recompiled many times and under many different editorships. It contains contributions from countless numbers of travellers and researchers."

Write an entry
Read more