Parameters:
x1 X coordinate of the top left corner of the face.
y1 Y coordinate of the top left corner of the face.
x2 X coordinate of the bottom right corner of the face.
y2 Y coordinate of the bottom right corner of the face.
id ID of the face. -1 not not known.
face A pointer to the IplImage with the image data.
和这个
Parameters:
param1 X coordinate of the top left corner of the face.
param2 Y coordinate of the top left corner of the face.
param3 X coordinate of the bottom right corner of the face.
param4 Y coordinate of the bottom right corner of the face.
param5 ID of the face. -1 not not known.
param6 A pointer to the IplImage with the image data.
你就明白了。 :)
While both are a-okay and used quite a lot, there is a distinct advantage to using parameter names in the declarations in your header files.
Parameters:
x1 X coordinate of the top left corner of the face.
y1 Y coordinate of the top left corner of the face.
x2 X coordinate of the bottom right corner of the face.
y2 Y coordinate of the bottom right corner of the face.
id ID of the face. -1 not not known.
face A pointer to the IplImage with the image data.
and this
Parameters:
param1 X coordinate of the top left corner of the face.
param2 Y coordinate of the top left corner of the face.
param3 X coordinate of the bottom right corner of the face.
param4 Y coordinate of the bottom right corner of the face.
param5 ID of the face. -1 not not known.
param6 A pointer to the IplImage with the image data.
It is best to provide other developers as much information as you can in as compact a format as you can. Forcing them to look up to the comments to determine something simple like what the parameters are is likely to take them out of the flow, make them less productive, and piss them off.
You ought to strive to name your functions well enough that they do not need to include the parameter name to be clear as to what they do. If you see a method prototype:
void save(const std::string&);
what is it doing? Is it saving that string? Or is it saving to a filepath represented by the string? Or...?
So you could do:
void save(const std::string& filepath);
to clarify. But this only clarified when someone is looking to at the header. If instead you do:
void saveToFilepath(const std::string&);
it should be quite clear everywhere. Of course, as you add more paramters, this becomes more cumbersome (but is one more reason to not add too many parameters; see Bob Martin's Clean Code on that; he commends nullary and unary functions, is hesitant about binary functions, quite reticent about trinary functions, and unwilling for any more than that).
So my advice is strive to not have a reason to include your parameters names in your function headers, not so much as an end in itself (though I am all for every bit of reduced duplication and increased brevity) but as a heuristic for how well you are naming your functions. (Note that if you are working with legacy code, you may want to cut yourself slack—but with the end goal in mind.)
This approach means that you will have to stop and think every time you type in a function header to check yourself, rather than following a black-and-white rule about whether to include the parameter names. Programmers tend to prefer to charge ahead rather than stopping to think about things like naming, but stopping to reflect is valuable on many different levels.
In sum, strive to not need to include the parameter names in the headers; and when you don't need them, don't bother to include them, for brevity and reduced duplication.
在最坏的情况下，程序员需要进行一些额外的输入。除了已提供的任何评论之外，它还显示了意图。我从来没有提倡过一种似乎纯粹是为了节省打字而存在的做法。在自动完成 iDE 的今天，变得冗长从未如此简单。
My rule of thumb is to name everything. Not every header file has nice comments before each function, and therefore the parameter name is all that remains to decipher the function when there is a lack of decent documentation.
In the worst-case, it's a bit of extra typing on the behalf of the programmer. It shows intent, in addition to any comments that have been provided. I have never, ever been one to advocate a practice that seems to exist purely to save typing. In these days of auto-complete iDEs, it's never been easier to be verbose.
发布评论
评论（4）
虽然两者都很好并且使用得相当多，但在头文件的声明中使用参数名称有一个明显的优势。
大多数文档系统（例如 doxygen）将解析您的头文件并生成文档。
例如，请查看此处： http://libface.sourceforge.net/doc/html/ classlibface_1_1_face.html
查看构造函数文档。
比较一下这个
和这个
你就明白了。 :)
While both are a-okay and used quite a lot, there is a distinct advantage to using parameter names in the declarations in your header files.
Most documentation systems (say, doxygen) will parse your header files and generate docs.
As an example, look here: http://libface.sourceforge.net/doc/html/classlibface_1_1_face.html
Look at the constructor documentation.
Compare this
and this
You get the point. :)
在声明中包含参数名称。
最好以尽可能紧凑的格式向其他开发人员提供尽可能多的信息。强迫他们查看评论来确定一些简单的事情，比如参数是什么，可能会让他们脱离流程，降低他们的生产力，并惹恼他们。
Include the parameter names in the declarations.
It is best to provide other developers as much information as you can in as compact a format as you can. Forcing them to look up to the comments to determine something simple like what the parameters are is likely to take them out of the flow, make them less productive, and piss them off.
您应该努力为您的函数命名得足够好，以便它们不需要包含参数名称就可以清楚地了解它们的功能。如果您看到一个方法原型：
它在做什么？它保存该字符串吗？或者它保存到由字符串表示的文件路径？或者...？
所以你可以这样做：
澄清。但这只有当有人查看标题时才会澄清。相反，如果你这样做：
到处都应该很清楚。当然，当您添加更多参数时，这会变得更加麻烦（但这也是不添加太多参数的另一个原因；请参阅 Bob Martin 的清洁代码；他推荐 nullary 和一元函数，但很犹豫关于二元函数，对三元函数相当沉默，并且不愿意了解更多）。
因此，我的建议是尽量不要有理由将参数名称包含在函数头中，与其说是目的本身（尽管我完全赞成减少重复和增加简洁性），不如说是作为一种启发式方法您正在命名您的功能。 （请注意，如果您正在使用遗留代码，您可能想放松一下自己，但要牢记最终目标。）
这种方法意味着您每次输入函数头时都必须停下来思考以检查自己，而不是遵循关于是否包含参数名称的黑白规则。程序员往往更喜欢勇往直前，而不是停下来思考命名之类的事情，但停下来反思在许多不同层面上都是有价值的。
总之，尽量不要需要在标头中包含参数名称；当您不需要它们时，为了简洁和减少重复，就不必费心包含它们。
You ought to strive to name your functions well enough that they do not need to include the parameter name to be clear as to what they do. If you see a method prototype:
what is it doing? Is it saving that string? Or is it saving to a filepath represented by the string? Or...?
So you could do:
to clarify. But this only clarified when someone is looking to at the header. If instead you do:
it should be quite clear everywhere. Of course, as you add more paramters, this becomes more cumbersome (but is one more reason to not add too many parameters; see Bob Martin's Clean Code on that; he commends nullary and unary functions, is hesitant about binary functions, quite reticent about trinary functions, and unwilling for any more than that).
So my advice is strive to not have a reason to include your parameters names in your function headers, not so much as an end in itself (though I am all for every bit of reduced duplication and increased brevity) but as a heuristic for how well you are naming your functions. (Note that if you are working with legacy code, you may want to cut yourself slack—but with the end goal in mind.)
This approach means that you will have to stop and think every time you type in a function header to check yourself, rather than following a black-and-white rule about whether to include the parameter names. Programmers tend to prefer to charge ahead rather than stopping to think about things like naming, but stopping to reflect is valuable on many different levels.
In sum, strive to not need to include the parameter names in the headers; and when you don't need them, don't bother to include them, for brevity and reduced duplication.
我的经验法则是给一切命名。并不是每个头文件在每个函数之前都有很好的注释，因此，当缺乏像样的文档时，参数名称就是解释函数的全部内容。
在最坏的情况下，程序员需要进行一些额外的输入。除了已提供的任何评论之外，它还显示了意图。我从来没有提倡过一种似乎纯粹是为了节省打字而存在的做法。在自动完成 iDE 的今天，变得冗长从未如此简单。
My rule of thumb is to name everything. Not every header file has nice comments before each function, and therefore the parameter name is all that remains to decipher the function when there is a lack of decent documentation.
In the worst-case, it's a bit of extra typing on the behalf of the programmer. It shows intent, in addition to any comments that have been provided. I have never, ever been one to advocate a practice that seems to exist purely to save typing. In these days of auto-complete iDEs, it's never been easier to be verbose.