记录std::函数参数的最佳实践

Best practice for documenting std::function parameters

本文关键字：最佳 参数 std 函数 记录      更新时间：2023-10-16

当使用std::function声明类型时，我发现我无法为模板实参分配形参名。例如，我发现这个简单的函数指针类型声明:

typedef void (*ArcCallback)(
  void *object, 
  double x_start, double y_start, 
  double x_finish, double y_finish, 
  double x_center, double y_center, 
  bool counterclockwise);

比这个std::function类型声明更具可读性:

typedef std::function<void(
  void *,
  double, double,
  double, double,
  double, double,
  bool)> ArcCallback;

尽管使用std::function带来了灵活性(例如，能够分配lambda或std::bind调用的结果)，但我错过了参数名称。当然，我可以在std::function声明中添加注释，但结果是笨拙的。更重要的是，我不认为ide会使用这些注释来提供参数提示。

其他有经验的c++从业者如何将模板参数的目的文档化为std::function ?广泛使用的库是否有大量使用此类类型的先例?

对于这个特定的代码，问题不在于std::function没有很好的方法来记录参数，问题在于对于任何函数来说，8个参数可能太多了。引入额外的类型可以很好地解决这个问题。

typedef void* CallbackObject;
struct Point {
  double x;
  double y;
};
enum CircularDirection {
  CLOCKWISE,
  COUNTERCLOCKWISE
};
struct ArcCallbackParam {
  CallbackObject object;
  Point start;
  Point finish;
  Point center;
  CircularDirection direction;
};
typedef std::function<void(const ArcCallbackParam&)> ArcCallback;

编辑:我意识到这并不能直接回答你的问题。为了回答你的问题，我不知道除了注释参数之外还有什么"解决方案"，但是添加类型和typedef可以帮助很多。

原始ArcCallback typedef中的参数名称仅用于自我文档目的。既然您有使用"冗余"参数名的习惯，那么您为什么不在std::function的情况下也做同样的事情呢?

typedef std::function<void (
  void *object, 
  double x_start, double y_start, 
  double x_finish, double y_finish, 
  double x_center, double y_center, 
  bool counterclockwise)> ArcCallback;

语言不禁止这样做

相关文章：