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等

用户.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 ，因此它很容易被一些编码人员随机删除。

我觉得我们心爱的代码从内部腐烂了，我想办法挽救它。

问题

如何 self 记录类型别名以指示它是如何/在何处调用的？？

我糟糕的解决方案

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 中的拇指一样突出。然后你可以问他们，“你是如何得出库不再需要这个声明的结论的，为什么删除它值得破坏我们的 API？”

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