我正在開發一個名爲StableClass的類。這個類是「穩定的」：用戶可以在這個類上依賴他們的代碼。該框架的未來版本將具有此類，並且它將向後兼容。如何將方法/ API標記爲實驗？

我想要的是添加一個方法到這個類，但我要告訴用戶這個特殊的新方法是實驗性的，並在未來可能會改變。

例如：

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屬性），但據我所知，此屬性不存在。

[更新]：

我要釋放的框架的穩定版本，與標記爲實驗少數的API。有時，需要一段時間才能找到正確的名稱，正確的參數或特定方法的正確功能，或者爲所有支持的平臺實施它。

我想告訴我的網友認爲「這是該框架的新的穩定版本我們還增加了這項新功能，但它是實驗性的，因爲它具有以下限制：......」。

所以，我有這個要求，其中穩定的版本可能有實驗性的功能。雖然這可能聽起來像是一個矛盾，但這是我的一個要求。

來源

2014-05-14 ricardoquesada

不是在語言標準。編譯器可以自由地將它作爲擴展來實現，但無論如何，我都會建議將它寫在文檔中，而不是在函數名稱或任何非標準屬性上擺弄。 – DevSolar

也許：一個實驗功能使整個庫實驗（在修訂控制中的一個實驗分支） –

這聽起來像它應該是一個文檔的東西，而不是代碼的東西... – twalberg

我認爲你是在正確的軌道上。 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時，他們會收到編譯器錯誤，告訴他們實驗方法不再可用。這將迫使他們通過自己的代碼並刪除使用實驗版本時所需的任何黑客。至少，他們所需要做的就是用MyMethod()查找/替換EXPERIMENTAL_MyMethod()。

的觀光：

簡單，易於使用。
很明顯看到什麼是實驗，什麼不是。
可繪。用戶可以在其代碼中輕鬆找到EXPERIMENTAL_函數調用。

缺點：

使穩定類中現有的實驗方法。
用用戶可能不想使用的不穩定方法污染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使用情況。

缺點：

需要工作來維持。
包裝和其他名稱空間可能會污染您的API。
using namespace Experimental; *不寒而慄*

來源

2014-05-14 19:52:11

這個答案非常適合我們的框架，因爲我們已經在使用'experimental'命名空間來爲類。 – ricardoquesada

雖然我還沒有測試過這個解決方案，但它似乎不適用於子類。如果用戶已經擁有了StableClass的子類，並且他想要使用新的實驗性功能，那麼他將需要從'experimental :: StableClass'繼承而來。雖然它看起來不是主要問題，但我更願意強制用戶更改現有代碼，以便使用新的實驗功能。 – ricardoquesada

正如一些評論所指出的，這需要源本身以外來處理。無論是通過文檔還是作爲您的版本控制系統中的一個分支。發佈庫的最終穩定版本時，您不希望讓人們通過並更改其代碼中的所有名稱，這與_experimental後綴會發生什麼情況相同。

添加在編譯器警告消息可能是好的，但也可能會激怒誰的「警告視爲錯誤」選項組運行的人。

來源

2014-05-14 18:44:06

*「發佈庫的最終穩定版本時，您不希望讓人們通過並更改其代碼中的所有名稱，這是_experimental後綴會發生的情況。」*這可能實際上是最好。例如，CSS使用供應商前綴（例如'-moz-border-radius'）執行此操作，因爲它指示可能會在發佈之前更改其行爲的屬性。同樣，添加「_experimental」前綴或後綴將強制API用戶重新評估其代碼，並在完成最終API實現後可能會刪除任何黑客。 –

@KarlNicoll好比喻。 Python有'from __future__'這不是實際上相同的東西，但類似 – ricardoquesada

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

隱藏在適當的定義不可靠的方法，將迫使用戶改變他們的項目/目標預處理設置，這樣他們就會知道他們正在處理的。

來源

2014-05-14 18:46:43 bigblackdot

Upvote。確保定義默認隱藏方法，因此用戶必須考慮他們要求的內容。 – ssube

這可能會導致鏈接器出現問題，我建議使用'EXPERIMENTAL'在公共/私人之間切換。好主意，但。 –

是的，這是一個有效的選項。但是這種方法的問題在於，它將啓用所有的實驗功能，並且用戶可能會在不知道實驗功能的情況下使用實驗功能。例如：用戶定義'EXPERIMENTAL'是因爲他想使用功能A，但是它也會啓用功能B.用戶可能會使用功能B（例如：IDE自動完成）而不知道它是實驗性的。 – ricardoquesada

如何將方法/ API標記爲實驗？

回答

重命名你的方法

創建一個包裝類

相關問題