Prepare a public headline for release

Question

I am interested in knowing what procedures you have in order to clean up public header files that you distribute to clients.

Some things that I would like to hear about are:

Comments are not intended for external consumption. Generally, I like to support closing documentation to code and comments, as this may 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, in any project involving several developers for any long period of time and the subsequent release of this source code, SCAN FOR OBSCENITIES (and other things that you should not have said, for example: "My boss made me do this "," This code is terrible, "etc.). Also, spellchecking comments can be helpful, as people have misspelled words, because of your trust.

Answer 2

Please make sure your headers do not generate any compiler warnings.

Answer 3

There is always someone (preferably more than one) going through the heading to look for something that looks unprofessional. You can use code formatting and other automated tools first.

For comments, ask them to look for something unprofessional or trial. Correct typos. Make sure they are accurate. Have a standard way to format them and stick to it.

Check all identifier names. They must be in style and professionally named.

Make sure you have all the necessary comments. This includes copyrights and contact information above. Come up with a standard method for documenting classes, etc. And secure it.

In principle, from my point of view, you want your headlines to look as if they were created by unmanned aerial vehicles without creativity or a sense of humor, but which are perfectly consistent (like CPA stereotypes). (This is like asking your developers to wear suits while clients visit the office — customers will be happier if they don't understand what your developers are actually doing.)

Answer 4

As a rule, it would be better if you had coding standards / formats for documents that clients would see that the developers themselves are watching when they first create the code, so you do not waste time cleaning up the code before release, for example now.

In addition, Visual Studio and several other IDEs have the option “Auto Formatting”, where you can customize the style and apply it to your code (tabs, spaces, etc.). I think that basically what you ask for here.

Answer 5

I am not very good at this issue, but for open source projects you often have a license and copyright agreement at the top of the title. This can lead to several legal issues.

Answer 6

In my experience, when an internally used heading is regularly and automatically cleaned up for public consumption, it is a difficult task and certainly error-prone. In the end, an inconsistent format or inappropriate comment will inevitably creep in.

In many cases, it is probably best for you to collapse everything into a small and clean interface, the title of which is always maintained as clean and as commented as possible; modifications to this file should go through, for example, a particularly thorough verification process.

Answer 7

Just as important as removing harsh comments adds the necessary ones. What you need to add:

• copyright / terms of use
• contact information for support
• links to documentation if it becomes available online
• documentation of open interfaces (return values, parameters, preconditions and post-conditions, etc.)
• warnings about functions / methods that are affected but not intended for use in production

Answer 8

G'day

In C ++, I like to use idleom-handle-Body to separate the implementation from the public interface as much as possible.

You must also ensure that any template, such as copyright notices, is consistent and relevant, for example. copyright does not expire in 2008 for the release of code today.

Be consistent across all publicly available header files for class naming, formatting, layout, and design conventions, otherwise this leaves an unprofessional impression on customers.

Make sure your header files do not “use” ads. Improper use of "use" dec can seriously damage things by unintended side effects.

As mentioned earlier, make sure your headers do not generate any warnings.

At last. make sure you have good API documentation for your header files.

Not like a company that provides a well-known product for searching zip codes. The first version of the C API comes with minimal documentation, which was largely based on the Windows GUI version. The header files simply consisted of functions whose parameters had only types and names. And no comments at all.

The only way to determine what the functions actually performed was to redesign the simple search example program provided and reconstruct it.

However, after I did this, I saved the BBC children who needed tens of thousands of pounds a year, because the addresses offered for fundraising packages were more likely than in previous years!