At Autodesk, like many companies, we produce our API reference documentation directly from programmer comments. In this blog I share a draft best practices document that I am hoping we can start using for our developers, when they write code comments.

There is a big difference between useful and useless comments, even though they take almost as much time to produce. Jeff Atwood has written an interesting blog post about avoiding what he calls undocumentation. 

The challenge I have ahead of me is teaching our developers at Autodesk how to write good code comments that result in usable and helpful API reference documentation. I have started work on a best practices document for our developers which can be found via this blog post.  

I'd be interested in hearing your own suggestions and receiving links to guidelines for writing code comments.