重命名方法

Question

我正在开发一个名为StableClass的类的框架。这个类是“稳定的”：用户可以在这个类上依赖他们的代码。该框架的未来版本将具有此类，并且它将向后兼容。

我想要的是在这个类中添加一个方法，但我想告诉用户这个特殊的新方法是实验性的，将来可能会改变。

示例：

class StableClass
{
public:
    void stableMethod1();
    void stableMethod2();
    void stableMethod3();
    void unstableMethod(); // How to tag this method as experimental ?
};

用户应该知道unstableMethod()是实验性的。 API可能在将来发生变化（或不发生变化）。

可能的选择：

在名称上添加experimental字作为后缀或前缀。例如：unstableMethod_experimental()
每次调用方法时都会登录到控制台
将其标记为已弃用，但在警告中说它是实验性的

还有其他选择吗？

我想拥有experimental属性，并且编译器在编译时会发出警告（如deprecated属性），但据我所知，这样的属性不存在

[UPDATE] ：

我想发布一个稳定版本的框架，其中一些API被标记为实验性的。有时需要花时间为特定方法找到正确的名称，正确的参数或正确的功能，或者为所有支持的平台实现它。

我想告诉我的用户“这是该框架的新稳定版本。我们还添加了这个新功能，但它具有实验性，因为它具有以下限制：......”。

所以，我有这个要求，稳定版本可以有实验性功能。虽然这听起来像是一个矛盾，但这对我来说是必须的。

Answer 1

#ifdef EXPERIMENTAL
    void unstableMethod(); // How to tag this method as experimental ?
#endif

在适当的定义下隐藏不可靠的方法将迫使用户改变他们的项目/目标预处理器设置，以便他们知道他们正在处理什么。

Answer 2

我认为你走在正确的轨道上。 CSS与特定于供应商的前缀类似。例如：

.my-css-class {
    /* Border-radius for CSS3 compliant browsers */
    border-radius: 2px;

    /* Border-radius for browsers where CSS3 border-radius support
     * is experimental, or non-standard */
    -webkit-border-radius: 2px;
    -moz-border-radius: 2px;
    -o-border-radius: 2px;
};

由于您的方法是实验性的，因此可以合理地假设该方法在您现在和您对API满意的时间之间可能会发生显着变化，并且存在某些风险。您的“实验性”API版本的用户可能必须围绕您的API实施黑客攻击以执行他们想要的操作，并希望他们能够向您报告问题，并让您更好地满足他们的需求。

当您的方法最终确定时，可能不再需要您的用户黑客，更糟糕的是，在他们的代码中引入错误，因此强制您的API用户重新评估他们的在使用最新版本的API之前，请确保代码正确无误。

你可以通过多种方式优雅地做到这一点，我能想到一对：

重命名方法

虽然您的API是实验性的，但您可以将此方法称为：

void EXPERIMENTAL_MyMethod();

然后，您可以删除EXPERIMENTAL_前缀。当您的用户选择将他们自己的代码更新到最新的API时，他们会收到编译器错误，告诉他们实验方法不再可用。这将迫使他们浏览自己的代码并删除使用实验版本时所需的任何黑客攻击。至少，他们需要做的就是用EXPERIMENTAL_MyMethod()查找/替换MyMethod()。

<强>赞成：

简单易用。
明显看到什么是实验性的，什么不是实验性的。
Greppable。用户可以在代码中轻松找到EXPERIMENTAL_函数调用。

<强> CONS：

在稳定的班级中提供实验方法。
使用用户可能不想使用的不稳定方法污染IDE自动完成。

创建包装类

像这样：

namespace MyApi
{
    namespace Experimental
    {
       class StableClass;
    }

    class StableClass
    {
    public:
        void stableMethod1();
        void stableMethod2();
        void stableMethod3();

        friend class Experimental::StableClass;
    };    

    namespace Experimental
    {
        class StableClass : public MyApi::StableClass
        {
        public:
            void unstableMethod();
        };
    }

使用“实验”命名空间，就像这样......

MyApi::Experimental::StableClass myStableClassInstance;

......而不是......

MyApi::StableClass myStableClassInstance;

...您明确声明使用Experimental命名空间版本的类的任何人都受制于开发人员的一时兴起。完成方法的稳定版本后，将其添加到课程的非实验版本中，并从实验版本中删除unstableMethod()。然后Experimental::MyClass实例的用户将收到编译器错误。然后，您的文档可以解释已发生的变化。

<强>优点：

很高兴看到，明确区分稳定和不稳定的API。
明确说明用户在使用Experimental命名空间时会遇到什么。
强制用户在发生更改时重新评估其实验性API使用情况。

<强> CONS：

需要维护工作。
Wrappers和其他名称空间可能会污染您的API。
using namespace Experimental; * shudder *

Answer 3

如某些评论中所述，这需要在源本身之外处理。通过文档或作为修订控制系统中的分支。在发布库的最终稳定版本时，您不希望让人们通过并更改其代码中的所有名称，即_experimental后缀会发生的情况。

添加编译器警告消息可能没问题，但是您也可能会激怒那些使用“将警告视为错误”选项设置的人。

如何将方法/ API标记为实验？

3 个答案:

重命名方法

创建包装类