I am a firm advocate of commenting code, but you need to make sure that you are commenting the right thing.  I worked on a project last year and then the project was paused.  I’m now back on it full time, some 6 months later.  I wrote most of the database code and all calls from the application to the database are via stored procedures.  All stored procedures have code headers that include:

• Description
• Used by
• Sample execution

and then a table showing:

Date, modified by, and reason

Also, all the different aspects of the code have a comment block on why it’s doing what it’s doing.

However, after 6 months and after commenting extensively, or so I thought, I still have no idea why I did half the things I did.

I’m now thinking that my code header should include a list of what the code needs to do, or maybe it’s just that my descriptions need a lot more information.

What I have discovered though is that whilst I do comment I need to do an awful lot more.

I’d be very interested to people’s thoughts on this.