When to comment code

2005-11-30 13:40:00

I saw a pretty decent post off of Slashdot on commenting your code, from Make the Software Shine.

This was interesting timing since yesterday as I was working on Scooby, I was noticing how many pieces of code were sadly lacking comments.

Of course it was the knee-jerk guilt reaction -- it's pretty well drilled into me that a good programmer comments his code. But then I was also thinking about how quickly the code is evolving, and that I've actually had to remove large swaths of comments along with code I was refactoring.

I thought the Weblog post raised an interesting point about when it's really appropriate to comment your code:

The point to start writing comments is... when the code is ready to be presented for others. This could be the time before commit to a main source repository, or insert your case here. For this time, I have pretty stable class design, and good chance my comments will live long.

I'm going to keep up with the inline comments in the code, but I believe I'll leave the more detailed JSDoc-style commenting until stuff starts to stablize a bit.