问有没有更好的方式在代码中注释参数的方向？

EN

考虑到这是一个文体问题，它会引起一些主观的反应，包括我的。:-)

有一些过程性语言确实要求将函数参数定义为输入或输出。在C++中，这在很大程度上是不必要的。

现代C++开发人员应该具有的一般心态是，更多地关注可变与不可变，以及接口而不是原始类型和数据。

当我们看一个这样的函数时：

void f(int x);

..。C++开发人员可以一目了然地告诉您'x‘用于输入。为什么？它是通过值传递的。没有办法以对调用者有任何影响的方式修改'x‘，因此传递给此函数的任何参数都不会被修改。

对于任何const引用也是如此：

void f(const Foo& read_only_foo);

以上绝对是一个严格的输入参数。当我们看一个这样的函数时：

void f(int& x);

我们通常可以假设f将修改x (不能保证这一点，但知道f做了什么应该会消除任何疑问)。

对于用户定义的类型，它变得有点模糊。

ostream& operator<<(ostream& os, const Foo& foo);

这里我们确定'foo‘是一个输入参数，因为它是不可变的。但是“os”又如何呢？它是一个输出参数，还是输入参数，两者都是？在严格的过程化语言中，输出参数通常意味着参数将被更改，但我们在这里也是从它读取的，所以两者都是。虽然我们将在“os”中调用对其状态有影响的方法，但在本机支持in/out参数的过程语言中，这并不是我们所认为的输出参数的方式。

关键是这种考虑参数的严格I/O方式可能会与这些类型的高级接口和面向对象设计完全混淆。在这里，一种更有用的看待事物的方法往往是实现接口的对象是可变的还是不可变的。在这里，“os”是可变的。该函数通常表示它将调用一些修改其状态的函数。

这个怎么样？

// fills the specified list with stuff
void some_list(list<int>& out_list);

在这里，它倾向于使用我们期望的输出参数的语义，也许更自然。对于像填充列表这样的东西，我们倾向于更直观地认为它是通过列表输出结果的函数。我甚至在名字前面加上了'out‘来强调这一点。但实际上，尤其是使用C++11，我们不应该像Stroustrup强调的那样编写这样的东西：

// returns a new list filled with stuff
list<int> some_list();

这实际上只剩下很少的地方可以证明in/out的区别是非常有用的(并且不是多余的，因为已经提供了通过值、引用、指针或r值引用将参数标记为可变/不可变的方法)。

结合关于函数正在做什么的清晰文档，通常没有关于它如何使用其参数的歧义，因此输入/输出约定往往做得很少，但添加了大量额外的代码，并可能促进一种更面向数据的思维方式，这是您应该努力摆脱的。

总而言之，我建议尽量避免这种约定。即使有很好的论据支持它，但这不是人们在C++中倾向于做的事情。如果你想让人们喜欢使用你的代码，而不是感到沮丧，你必须学会跟随普通大众倾向于理解和喜欢的东西。任何异国情调的东西都会把人吓跑。

如果您绝对、狂热地希望指定所有内容都是内部或外部的，我建议您使用一种侵入性最小的解决方案，如文档样式或命名约定。一定要避免不做任何事情的宏。这将要求读者每次检查这些宏是否做了什么，实际上，什么也不做。命名约定或文档样式不需要这样的检查。

最后，引用C++创建者自己的一句话：

关于宏的第一条规则是:除非迫不得已，否则不要使用它们。几乎每个宏都会在编程语言、程序或程序员中显示出缺陷。-- Bjarne Stroustrup