There are generally 2 camps for commenting code:
- My code is self-documenting.
- I want the next person to know what I was doing and why. Oh, and I want to be able to remember when I go back in 6 months.
People in this camp usually have more verbose method, property, and variable names.
People in this camp sometimes over comment. This folks will take a Insert Into table Select From tableB and put this comment at the top "this inserts a row into tableA from tableB".
- Comment why I am doing what I am doing and why I am doing it this particular way. Any good developer should be able to figure out what the code does, but not necessarily the why. Thanks Roger Plowman and those who seconded his comment.
- Comment so a novice, either in programming or business knowledge, can understand what the code does and why. Several people mentioned it in the thread.
- Create the why and how comments BEFORE beginning. Really this is putting together a plan, and will probably be the hardest one for me as I like to "dive" right in. Thanks Jay Holovacs and others who mentioned this.
- Push for and get an intranet Wiki or Knowledge Base. My first job had one and it was great. Where I'm at now does not, which means the developer who wrote it, supports it. Not that I don't want to support my code, but I don't need to be the only one who can do it. Thanks again to Roger Plowman and others.
So now you know that my "commentary" is mediocre at best, but how's yours?