Prepare public header for release

Question

I'm interested in hearing what routines you have for cleaning up public header files you distribute to customers.

Some things I'd like to hear your opinions on are:

Comments not meant for external consumption. Generally I like keeping documentation close to the code and comments like this might not be a good idea to share:

/**
 * @todo Should we change the signature of this function to
 * make it obvious that xxx is really yyy?
 */

or perhaps:

/**
 * @todo Add support for feature X
 */

Inconsistent tab styles:

void functionA(int a, 
     int b,
     int c,
     int d);

void functionB(int a,
               int b,
               int c);

Are there any tools for preparing headers or code in general for release?

Answer 1

You should ALWAYS, on any project involving multiple developers for any extended period of time and the subsequent release of that source code, SCAN FOR OBSCENITIES (and other things you shouldn't have said, e.g., "My boss made me do this", "This code is terrible", etc). Also, spell-checking the comments can be helpful, as people incorrectly spelling words saps from your credibility.

Answer 2

Please make sure that your headers don't generate any compiler warnings.