What is the best way to document my code?

[manasij7479]

I thought I was doing a nice job, using comments and occasionally doxygen.
But a recent 'close to blunder' situation is making me rethink my practices.

I was writing a small interpreter and suddenly realised that I needed to change most of the class and function interfaces to use pointers instead of just copying a value (some unintended object splicing occurred).

After about 15 mins of trying to change the code to adapt to the changes, I realised that I needed to make the whole thing more loosely coupled into distinct modules (such that, say ..the expression evaluator, does not in any way depend on the inner workings of the lexer).
That invalidated some of my attempts in documenting what I did earlier.

Is there a way to make the process of 'updating' the documentation with code easier ?

[Salem]

Software design - Wikipedia, the free encyclopedia
Once you're past the stage of a couple of classes, or a couple of thousand lines of code, you need to start actively planning your code at a higher level. You don't have to produce a complete detailed design before you start coding, but you should have enough to give you some kind of road map for the direction you want to go.
So when it comes to choosing class interfaces, you can at least look ahead to your goal to help you choose something which moves you in the right direction.

Design (like anything else) is a practiced skill. An informal design can be sketched, evaluated and thrown away in a couple of hours, but it might take you a week or more of code hacking to come to the same conclusion.

Revision control - Wikipedia, the free encyclopedia
Comparison of revision control software - Wikipedia, the free encyclopedia
Get one of these - you'll be thankful the first time a series of edits goes badly wrong, and you just want to get back to something earlier which worked.

[manasij7479]

I'd start planning more thoroughly from now on.....not just in my mind when bored during public transport.

Revision control - Wikipedia, the free encyclopedia
Comparison of revision control software - Wikipedia, the free encyclopedia
Get one of these - you'll be thankful the first time a series of edits goes badly wrong, and you just want to get back to something earlier which worked.

I'm really happy that I use svn now, straight from the terminal though (learnt from the svn-book). Thus I could restore the revision just before it went haywire.

[BobMcGee123]

You need version control, as mentioned. I've found the Unix text utilities, particularly SED and GREP, instrumental in physically making changes to vast amounts of code (but again, you need to have some sort of version control to do this...I know it takes me 8 trillion mistakes before I finally get it to work).

If you're running on Windows you can install Cygwin and just select the text utilities from the download (I apologize if you already know about all this, which you probably do).

[manasij7479]

Get one of these - you'll be thankful the first time a series of edits goes badly wrong, and you just want to get back to something earlier which worked.

You need version control, as mentioned.

I previously set up an svn server repo in my /var/ directory.
But I just got myself a sourceforge account, their service literally rocks...(so many 'management' tools in the same place.)