Posts

Showing posts from December, 2005

Comments

Comments are one of those things I tend to forget about until someone brings it up. I have heard many exaggerated claims about comments dramatically improving a project or how they are essential for success on large projects. I am not sure how big a project needs to be to be considered 'large'. 500k LOC? 1M LOC? That is a conservative estimate for the size of some projects I have worked on and they seemed pretty big. So based on my experiences, are comments really that useful? And what makes a good comment anyway? Should I comment every function? I thought it was about time I had a little rant. It has been a while ;)


Firstly, comments are documentation. Writing any kind of documentation you need to know who your audience is. Writing a user manual is different from writing a business pitch or writing a programmers reference. Fortunately in the case of comments your audience is easy, it is other programmers ... or more likely than not it will be you looking back over some piece o…