自我记录一个类型别名（typedef），表示它将被用于另一个特定的类 [英] Self-document a type-alias (typedef) to indicate that it will be used in another certain class

问题描述

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

在下面的示例中，类 User 定义一个别名 User :: type ，应该仅在类库中通过 T ::型。

这是图： -

Library.h

库< T> code>只有 T 定义了一个别名（例如 T :: type ）。

  #include< iostream> 
 class Base {}; //虚拟为了例子
 template< class T> class Library {
 Base * t = nullptr; 
 public：typename T :: type getValue（）{return static_cast< typename T :: type>（t）;} 
 //一些复杂的函数， T :: aType :: doSomething（）
}; 
  

在实际情况下，库< T> 预期许多别名例如 T :: aType ， T :: bType ， T :: callbackType 等

User.h

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

  class Derived：public Base {}; //虚拟为了例子
 class User {
 public：using type = Derived *; //<  -  poorly recorded 
 // ... other alias eg aType = int *，bType = SomeClass * 
 // ...其他复杂函数
}; 
  

这是用法（ 完整演示 ）： -

  int main（）{
库< User> LIB; 
 lib.getValue（）; 
 std :: cout<<OK<< std :: endl; 
} 
  

问题

请注意， User :: type 真的缺少自我文档。

在现实生活中，大多数编程人员 - 包括设计它的人 - 忘记了什么 User :: type 是为。

User :: type 在 User.h ，所以这是一个很容易被一些编码人员随机删除的目标。

我觉得我们所爱的代码从内部腐烂，我想到了如何保存它。

问题

如何自我记录类型别名以指示/ em> ？

我可怜的解决方案

1。评论

  class User {
 / **用于Library.h * / 
 public：使用type = Derived *; 
  

它变得很脏，我仍然更喜欢使用C ++ - 语义而不是随机评论。 p>

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

  class User {
 / **它用于Library.h * / 
 public：using LIBRARY_type = Derived *; 
  

这很麻烦。

strong>注意：此问题类似于如何自我记录由模板库类调用的回调函数？，但是这一个是关于 type-def ，而那个是关于回调。

解决方案

似乎你唯一的实际问题是一些编程人员随机删除它是一个容易的目标。

解决这个问题的方法不是痴迷于自我文档和名称，而是要进行同行评审和回归测试 EM>。为什么你的团队中的编码人员会随机删除这些东西，并避开它？这需要停止。

您可以通过简单的代码注释来节省管理头痛的必须回滚此类更改：

  / ** 
 *提供供图书馆使用。 
 * / 
使用type = Derived *; 
  

就是这样。这就是你需要的。这不是肮脏的在最轻微的—它告诉其他编码器为什么类型声明存在，并且如果有人删除，将会像 diff 它。那么你可以问他们：你如何得出结论，图书馆不再需要这个声明，为什么要删除它值得破坏我们的API？

总之，这只是一个人的问题。在类型的成员类型的标准库中有很多示例，所以从技术角度来看，您已经在做你应该做的事了。不要尝试在反映您的类型的期望使用的名称中的鞋角;使名称描述它是什么是。 C ++委员会与 std :: move 相同的错误

How to self-document a type-alias that is used in another certain library?

In the below example, class User defines an alias User::type that is supposed to be referred only in class Library via T::type.

Here is the diagram :-

Library.h

Library<T> expected only T that defines a certain alias (e.g. T::type in this example).

#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()
};

In real cases, Library<T> expected many alias e.g. T::aType, T::bType, T::callbackType, etc.

User.h

To use the above library, ::type has to be defined e.g. as below :-

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
};

Here is the usage (full demo):-

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

Problem

Notice that User::type really lacks self-documentation.
In real life, most coders - including ones who designed it - forget what User::type is for.

User::type is not referred internally in User.h, so it is an easy target to be randomly deleted by some coders.

I feel that our beloved codes are rotten from inside, and I think about ways to save it.

Question

How to self document the type alias to indicate how/where it is called?

My poor solutions

1. comment

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

It gets dirty pretty fast, and I still prefer using C++-semantic rather than random comment.

2. make the type name more descriptive

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

It is quite messy.

Note: This question is similar to How to self-document a callback function that is called by template library class?, but this one is about type-def while that one is about callback.

解决方案

It seems that your only actual problem here is that "it is an easy target to be randomly deleted by some coders".

The solution to this is not to obsess over self-documentation and names, but to institute peer review and regression tests. Why are coders on your team "randomly deleting" things and getting away with it? That needs to stop.

You can probably save the administrative headache of having to rollback such a change, with a simple code comment:

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

That's it. That's all you need. It's not "dirty" in the slightest — it tells other coders why the type declaration exists, and will stand out like a sore thumb in diffs if anyone removes it. Then you can ask them, "how did you conclude that Library no longer requires this declaration, and why is removing it worth the breakage of our API?"

In short, this is only a human problem. There are plenty of examples in the standard library of member types called type, so from a technical standpoint you're already doing what you should. Don't try to shoe-horn in names that reflect your type's expected usage; make the name describe what it is. The C++ committee made the same mistake with std::move!

这篇关于自我记录一个类型别名（typedef），表示它将被用于另一个特定的类的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！