原型参数名称

Question

在我的标题中,我有一个这样的原型声明:

void move(int, int);

我可以省略参数名称,这就是我从C中习惯的方法.我这样做是为了让我不必保持参数名称同步 - 如果它们在原型和实现之间有所不同,那就非常混乱了.

现在,我正在使用Doxygen记录我的所有代码,并且我决定将所有注释放入标题中.现在我必须引用在实现中定义但不在头文件中定义的参数名称:我发现这令人困惑.

/**
 * Moves the entity to the specified point.
 * @param x The x coordinate of the new position.
 * @param y The y coordinate of the new position.
 */
void move(int, int);

在生成的Doxygen HTML中,要弄清楚哪个参数是哪个参数并不容易.当然,人们可以遵循相同的顺序,但如果有一个参数,它仍然令人困惑.

另一种方法是复制参数名称并尝试使它们保持同步.但是,有些人不鼓励这种方法,说标题参数应该以双下划线开头,以便方法的用户不可能使用相同的名称(在_C++中不允许以__开头的名称).

你怎么做呢？

Answer 1

如果不清楚该参数的用途,那么在标题中不命名参数是一个可怕的想法.标题应该是代码的文档,以便尝试使用它的人可以避免阅读实现.正如您所发现的那样,按名称记录参数是没有意义的,然后不告诉用户哪个是哪个.这并不是说它们必须匹配,但在标题中它们应该对代码的用户有意义.在实施中,选择最适合您的名称.例如,拥有以下内容是完全可行的:

.H:

void move(int x, int y);

的.cpp:

void move(int deltaX, int deltaY)
{
   ...

唯一有意义的事情(如果你关心其他程序员使用你的代码)来忽略参数名称的时候,那就是它很明显地表明了参数的作用.例如

void SetNumPotatoes(int);
void EnableLights(bool);
void InitFoo(Foo&);

// but then...
T& GetItem(int);  // probably obvious enough, but does typing 'index' kill you?
void DoSomething(bool, float, int);  // someone using this will say, "WTF?"

Answer 2

当然,如果"在C++中不允许以__开头的名称",你不应该在原型中使用它们:-) ^*a

我认为有两种方法可以做到这一点.

一,您可以确保评论中的参数顺序始终与原型中的顺序相匹配.

或者,两个,您实际上也可以将真实姓名放在原型中.

我自己,我更喜欢第二种方法,因为我喜欢能够告诉传入哪些参数,即使函数没有注释(或者更糟糕的是,注释已经过时).这样的原型更容易:

void move(int xcoord, int ycoord);

比它:

void move(int, int);

在某些环境中,我们甚至已经将构建过程确保所有函数原型都具有与函数定义相同的参数.

^*a)这些标识符实际上不适用于常规程序.cpp0x的第17.6.3.3.2节(但这种限制在C和C++中已存在很长时间)状态:

某些名称和函数签名集始终保留给实现:

• 每个包含双下划线__或以下划线后跟大写字母开头的名称都保留给实现以供任何使用.
• 以下划线开头的每个名称都保留给实现,以用作全局名称空间中的名称.

换句话说,不要将它们用于您自己的目的.