Prepare public header for release

Question

Hi!

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.

Answer 3

It'd generally be better if you had coding standards/formats for documents customers will see that the developers themselves follow when they first create the code, so you're not spending time cleaning up code before release, such as now.

Also, Visual Studio and several other IDE's have an "Auto Formatting" option where you can set up a style and it is applied to your code (tabs, spaces, that sort of thing). I think that's mostly what you're asking for here.

Answer 4

Have a look at GNU Indent, it can automatically reformat C header files.

Answer 5

I'm not very familiar with the subject, but for open source projects you often have the licence and copyright statement at the top of the header. This can avoid several juridic issues.

Answer 6

G'day,

In C++ I like to use the Handle-Body idiom to decouple the implementation as much as possible from the public interface.

You should also make sure that any boilerplate, e.g. copyright notices, is consistent and up to date, e.g. copyright doesn't expire in 2008 for code released today.

Be consistent across all public header files for naming conventions, formatting, layout and class design otherwise it leaves an unprofesional impression on customers.

Make sure that there are no "using" declarations in your header files. Misuse of "using" dec's can seriously screw things up with inadvertent side effects.

As mentioned previously, make sure that your headers don't generate any warnings.

Finally. make sure you've got some good API documentaion to go with your header files.

Don't be like a company who provides a well known postcode lookup product. First version of the C API came with minimal documentation that was heavily based on the Windows GUI version. The header files simply consisted of functions whose parameters only had types and no names. And no comments at all.

Only way to work out what the functions actually did was to reverse engineer a simple lookup example program provided and reverse engineer it.

Still, after managing to do that I saved BBC's Children in Need tens of thousands of pounds per year because the addresses provided for fund-raising packs were more likely to be correct than in previous years!

HTH

cheers, Rob

Answer 7

In my experience having an internally used header routinely and automatically cleaned up for public consumption is a hard task, and definitely error prone. Eventually the inconsistent format or the inappropriate comment will inevitable creep through.

In many cases you are probably better off wrapping everything into a small and clean interface, whose header is always maintained as clean and as commented as possible; modifications to that file should undergo, for instance, a particularly careful review process.

Answer 8

Just as important as removing crufty comments is adding necessary ones. Things you might need to add:

• copyright/terms-of-use header
• contact information for support
• links to documentation if it is being made available online
• documentation of public interfaces (return values, parameters, pre- and post-conditions, etc)
• warnings on functions/methods that are exposed but not intended for production use

As far as formatting tools go, check out the recent stackoverflow discussion about Best C++ Code Formatter/Beautifer, wherein AStyle is currently the top-ranked.

Answer 9

Always have somebody (preferably more than one) go through the header to look for anything that looks unprofessional. You can use code formatters and other automatic tools first.

For comments, have them look for anything unprofessional or tentative. Correct misspellings. Make sure they're accurate. Have a standard way to format them, and stick to it.

Check all identifier names. They should conform to a style guide and be professionally named.

Make sure all necessary comments are there. This includes copyright and contact information at the top. Come up with a standard method of documenting classes and such, and enforce it.

Basically, from my point of view, you want your headers to look like they were produced by drones without creativity or a sense of humor, but who are perfectly consistent (sort of like CPA stereotypes). (It's sort of like asking your developers to wear suits while customers are visiting the office - the customers will be happier if they don't see what your developers are really like.)