GUI and Rapid Application Development 1542

What kind of document do you mean?

No, I don't do it in a separate word-processor document. These usually won't keep up with the code.

Yes, I do document the code in various ways, within the source code:

1) I use meaningfulandlongenoughidentifiernames. Emacs's M- makes it easy to "type" such names. I'm not afraid of using them. And I frown upon those who would use abbrids.

2) I use comments to describe what (1) fails to do. I also use javadoc style comments to document the interfaces, e.g. what a function is supposed to do; and how its arguments and return value should look like. Very often, you'll need to document here clearly who (caller or callee) owns the objects pbutted in or out.

3) My policy of using VC is to check in frequently and check in with as small change sets as possible. And I always write meaningful change logs. In Emacs, Ctrl-x v l (it invokes "cvs log", "svn log" or "rlog" behind the scene, depending on which VC backend is being used) will show the log messages of the past changes. This is very useful.

And you should! The sooner the better.

How about diffs with older versions? This is useful for tracking changes when you're hunting down the root cause of differences in behaviour of various versions of your programs.

And where do you keep the change logs? VC encourages you to write a log message when you check in your changes. And it's easy to read back the logs.

I use VC (RCS) even for small projects, because I know it improves my productivity. And I know that if it grows to a bigger projects, it wouldn't save me any time and effort if I started using VC later.

You COULD do that with your beloved backups. Just keep 1 directory tree for each version of your program. And use 'diff -r'. But it gets difficult and error-prone once you've got a few versions to manage. And it becomes mission impossible when you have to handle a few branches! That's why people invented VC tools, instead of simply sticking with backups.

--