Since I joined Autodesk, I have had the opportunity to work with multiple SDKs throughout the Media and Entertainment (M&E) division. I am working on trying to improve the consistency and effectiveness of our SDK documentation across various products. One step towards this is agreeing on a set of guidelines for developers writing code comments that are transfomed into SDK reference documentation.

I have written a draft document describing what I consider to be best practices for writing code comments, that are transformed into API documentation using doxygen. Most of the document is general enough though that it should apply to comments processed by other documentation generating tools such as Doc-o-matic and Sandcastle as well.

I am posting a link to the document here because I am interested in hearing any feedback from other developers about their thoughts regarding these guidelines, and to share there own suggestions for writing effective code comments.

You can find the document "Writing Code Comments for Effective API Reference Documentation" at http://docs.google.com/View?id=dgjz7z25_129f4sqrrdx.