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:
- 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.