准备发布的公共标头
我有兴趣听听您有哪些清理公共头文件的例程 分发给客户。
我想听听您的意见是：
评论不适合外部消费。 一般来说，我喜欢将文档放在身边 像这样的代码和注释可能不是一个好主意来分享：
/**
* @todo Should we change the signature of this function to
* make it obvious that xxx is really yyy?
*/
或者也许：
/**
* @todo Add support for feature X
*/
不一致的选项卡样式：
void functionA(int a,
int b,
int c,
int d);
void functionB(int a,
int b,
int c);
是否有任何工具可以准备一般发布的标题或代码？
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?
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（8）
对于涉及多个开发人员的任何项目以及该源代码的后续发布，您应该始终扫描脏话（以及其他您不应该说的话，例如“我的老板让我这样做”， “这段代码太糟糕了”，等等）。 此外，对评论进行拼写检查也很有帮助，因为人们拼写错误的单词会降低你的可信度。
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.
请确保您的标头不会生成任何编译器警告。
Please make sure that your headers don't generate any compiler warnings.
始终让某人（最好不止一个）检查标题以查找任何看起来不专业的内容。 您可以首先使用代码格式化程序和其他自动工具。
对于意见，让他们寻找任何不专业或试探性的内容。 纠正拼写错误。 确保它们准确。 有一个标准的方法来格式化它们，并坚持下去。
检查所有标识符名称。 它们应该符合风格指南并采用专业名称。
确保所有必要的注释都在那里。 这包括顶部的版权和联系信息。 提出一种记录类等的标准方法，并执行它。
基本上，从我的角度来看，你希望你的标题看起来像是由无人机制作的，没有创造力或幽默感，但完全一致（有点像注册会计师的刻板印象）。 （这有点像要求您的开发人员在客户访问办公室时穿西装 - 如果客户看不到您的开发人员的真实情况，他们会更高兴。）
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.)
如果您拥有文档的编码标准/格式，那么通常会更好，客户会看到开发人员在首次创建代码时遵循这些标准/格式，这样您就不会像现在一样在发布之前花时间清理代码。
此外，Visual Studio 和其他几个 IDE 有一个“自动格式化”选项，您可以在其中设置样式并将其应用于您的代码（制表符、空格等）。 我想这主要是你在这里要求的。
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.
根据我的经验，定期自动清理内部使用的标头以供公共使用是一项艰巨的任务，而且肯定容易出错。 最终，不一致的格式或不恰当的评论将不可避免地蔓延开来。
在许多情况下，您可能最好将所有内容包装到一个小而干净的界面中，其标头始终保持尽可能干净并带有注释； 例如，对该文件的修改应经过特别仔细的审查过程。
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.
我对这个主题不太熟悉，但对于开源项目，您通常会在标题顶部看到许可证和版权声明。 这可以避免一些司法问题。
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.
与删除粗鲁的评论同样重要的是添加必要的评论。 您可能需要添加的内容：
Just as important as removing crufty comments is adding necessary ones. Things you might need to add:
天啊，
在 C++ 中，我喜欢使用 Handle-Body 习惯用法 尽可能地将实现与公共接口分离。
您还应该确保任何样板（例如版权声明）是一致且最新的，例如今天发布的代码的版权不会在 2008 年到期。
所有公共头文件的命名约定、格式、布局和类设计应保持一致，否则会给客户留下不专业的印象。
确保头文件中没有“using”声明。 滥用“使用”dec 可能会因无意的副作用而严重搞砸事情。
如前所述，请确保您的标头不会生成任何警告。
最后。 确保你有一些好的 API 文档来配合你的头文件。
不要像一家提供众所周知的邮政编码查找产品的公司。 C API 的第一个版本附带了最少的文档，这些文档很大程度上基于 Windows GUI 版本。 头文件仅由函数组成，其参数只有类型而没有名称。 并且根本没有评论。
弄清楚这些函数实际执行的操作的唯一方法是对提供的简单查找示例程序进行逆向工程并对其进行逆向工程。
尽管如此，在设法做到这一点之后，我每年为 BBC 的 Children in Need 节省了数万英镑，因为为筹款包提供的地址比前几年更有可能是正确的！
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!