函数声明应该包括参数名吗?

Should function declarations include parameter names?

本文关键字：参数 包括 声明 函数      更新时间：2023-10-16

你会考虑哪种更好的编码风格:在头文件中声明函数/方法的参数名，还是只在源文件中声明，因为两者都可以做到?如果您实际上考虑仅在源文件中声明函数/方法的参数名，那么如何声明默认值呢?

外标题:

//One.hpp
#ifndef ONE_HPP
#define ONE_HPP
namespace eins {
/** brief description
 *  
 * param one represents ....
 * param two represents ....
 */
void function(int,int);
}
#endif
// One.cpp
#include "One.hpp"
eins::function(int one,int two) {
  //Do stuff//
}

里面的标题:

//One.hpp
#ifndef ONE_HPP
#define ONE_HPP
namespace eins {
/** brief description
 *  
 * param one represents ....
 * param two represents ....
 */
void function(int one,int two);
}
#endif
// One.cpp
#include "One.hpp"
eins::function(int one,int two) {
  //Do stuff//
}

我个人的观点是第一种方式更好，因为用户实际上被迫阅读注释/API，而不能被误导到只阅读参数名。但是我不确定这一点，实际上声明默认值会打破我的风格，因为你必须在函数/方法的头声明中这样做。

虽然两者都可以，而且使用得很多，但是在头文件的声明中使用参数名有一个明显的优势。

大多数文档系统(比如，氧)会解析你的头文件并生成文档。例如:http://libface.sourceforge.net/doc/html/classlibface_1_1_face.html

查看构造函数文档

做比较
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.

你明白了。:)

在声明中包含参数名。

最好以尽可能紧凑的格式向其他开发人员提供尽可能多的信息。强迫他们查找注释来确定一些简单的东西，比如参数是什么，可能会使他们脱离流程，降低他们的工作效率，并惹恼他们。

您应该努力为您的函数命名得足够好，以至于它们不需要包含参数名来清楚地说明它们的作用。如果你看到一个方法原型:

void save(const std::string&);

它在做什么?它保存了那个字符串吗?还是保存到字符串表示的文件路径?或者…?

你可以这样写:

void save(const std::string& filepath);

澄清。但这只澄清了当有人看着头。如果你这样做:

void saveToFilepath(const std::string&);

应该到处都很清楚。当然，随着您添加更多参数，这将变得更加麻烦(但这是不添加太多参数的另一个原因;参见Bob Martin的Clean Code;

他推崇一元和一元函数，对二元函数犹豫不决，对三元函数相当缄默，除此之外不愿再做任何事。

所以我的建议是尽量不要有理由在函数头文件中包含参数名，这本身并不是一个目的(尽管我完全赞成减少重复和增加简洁)，而是作为一种对函数命名的启发。(注意，如果您使用的是遗留代码，您可能想让自己放松下来，但要牢记最终目标。)

这种方法意味着每次键入函数头文件时都必须停下来仔细考虑是否要包含参数名，而不是遵循非黑即白的规则。程序员倾向于向前推进，而不是停下来思考诸如命名之类的事情，但是停下来反思在许多不同的层面上都是有价值的。

总而言之，尽量避免需要在头文件中包含参数名;当你不需要它们的时候，为了简洁和减少重复，就不要把它们包括进去了。

我的经验法则是给所有东西命名。并不是每个头文件在每个函数之前都有很好的注释，因此，当缺乏像样的文档时，参数名是用来解释函数的全部。

在最坏的情况下，它代表程序员进行了一些额外的输入。除了已提供的任何评论之外，它还显示了意图。我从来没有提倡一种似乎纯粹是为了节省打字而存在的做法。在这些自动完成的ide中，没有比这更容易的了。

相关文章：