c++ - 自记录类型别名(typedef)以指示它将在另一个特定类中使用

Question

如何 self 记录在另一个特定库中使用的类型别名？

在下面的示例中，类 User定义别名 User::type应该只在类 Library 中引用通过T::type 。

这是图表:-

库.h

Library<T>仅预计T定义某个别名(例如本例中的 T::type)。

#include <iostream>
class Base{};     //dummy for the sake of example
template<class T>class Library{
    Base* t=nullptr;
    public: typename T::type getValue(){return static_cast<typename T::type>(t);}
    //some complex function, e.g. T::aType::doSomething()
};

在真实案例中，Library<T>预期有许多别名，例如T::aType , T::bType , T::callbackType等

User.h

要使用上述库，::type必须定义，例如如下:-

class Derived : public Base{};  //dummy for the sake of example
class User{
    public: using type=Derived*;//<-- poorly documented
    //... other alias e.g. aType=int*, bType=SomeClass*
    //... other complex functions
};

这是用法( full demo ):-

int main(){
     Library<User> lib;
     lib.getValue();
     std::cout<<"OK"<<std::endl;
}

问题

请注意User::type确实缺乏 self 文档。
在现实生活中，大多数程序员 - 包括设计它的人 - 忘记了什么 User::type是为了.

User::type User.h 中未内部引用，因此很容易被一些编码员随机删除。

我觉得我们心爱的代码已经从内部腐烂了，我正在思考如何挽救它。

问题

如何自行记录类型别名以指示其调用方式/位置？

我糟糕的解决方案

1。评论

 class User{
    /** It is used for Library.h */
    public: using type=Derived*;

它很快就会变脏，而且我仍然更喜欢使用 C++ 语义而不是随机注释。

2。使类型名称更具描述性

 class User{
    /** It is used for Library.h */
    public: using LIBRARY_type=Derived*;

很乱。

注意:此问题类似于 How to self-document a callback function that is called by template library class? ，但这一个是关于 type-def而那个是关于 callback 。

Answer 1

看来您这里唯一的实际问题是“它是一个很容易被某些编码员随机删除的目标”。

解决这个问题的方法不是沉迷于 self 文档和名称，而是建立同行评审和回归测试。为什么你团队中的程序员会“随机删除”一些东西并侥幸逃脱？这需要停止。

您可以通过简单的代码注释来避免必须回滚此类更改的管理难题:

/**
 * Provided for use by Library.
 */
using type=Derived*;

就是这样。这就是你所需要的。它一点也不“脏”——它告诉其他编码人员为什么存在 type 声明，并且如果有人删除它，它会像 diff 中的拇指酸痛一样突出。然后你可以问他们，“你是如何断定 Library 不再需要这个声明的，为什么删除它值得破坏我们的 API？”

总之，这只是人的问题。在名为 type 的成员类型标准库中有很多示例，因此从技术角度来看，您已经在做您应该做的事情了。不要尝试使用反射(reflect)您类型的预期用途的名称；让名称描述它是什么。。 C++ 委员会在 std::move 上犯了同样的错误!