C++ 中不容忽視的API 錯誤設計

  對于許多C ++開發人員來說，API設計可能會在其優先級列表中排名第3或第4。大多數開發人員都傾向于使用C ++來獲得原始功能和控制權。因此，性能和優化的想法占據這些開發者的時間的百分之八十。

 
  當然，每個C ++開發人員都會考慮頭文件設計的各個方面，但是API設計不僅僅是頭文件設計那樣。事實上，我強烈建議每一個開發人員在其API的設計上，無論是面向公共還是面向內部，都給予一些幫助，因為這樣可以節省你大量的維護成本，提供平滑的升級路徑，并為你的客戶節省麻煩。

 
  下面列出的許多錯誤都是我自己的經驗和我從Martin Reddy的精彩書籍《C ++ API Design》（我強烈推薦的書）中學到的東西的結合。如果你真的想要深入了解C ++ API設計，那么你應該閱讀Martin Reddy的書，然后使用下面的列表作為更多的清單來強制執行代碼審查。

錯誤＃1：不將你的API放在命名空間中

為什么這是一個錯誤？

  因為你不知道將使用哪個代碼庫，特別是對于外部API。如果不將API功能限制在命名空間中，則可能導致與該系統中使用的其他API發生名稱沖突。

 
例如：讓我們考慮一個非常簡單的API和使用它的客戶端類：

//API - In Location.h
class vector
{
public:
  vector(double x, double y, double z);
private:
  double xCoordinate;
  double yCoordinate;
  double zCoordinate;
};
//Client Program
#include "stdafx.h"
#include "Location.h"
#include <vector>
using namespace std;
int main()
{
  vector<int> myVector;
  myVector.push_back(99);
  return 0;
}

 
  如果有人試圖在同時使用std::vector的項目中使用這個類，他們會得到一個錯誤:
   “error C2872: ‘vector’: ambiguous symbol”
這是因為編譯器無法決定客戶端代碼引用的向量是std::vector還是location.h中定義的vector對象。

 
如何解決這個問題？

 
始終將API放在自定義命名空間中，例如：

//API
namespace LocationAPI
{
  class vector
  {
  public:
    vector(double x, double y, double z);
  private:
    double xCoordinate;
    double yCoordinate;
    double zCoordinate;
  };
}

 
  另一種方法是為所有公共API符號添加一個唯一的前綴。如果遵循此約定，我們將調用我們的類“lvector”而不是“vector”。此方法用于OpenGL和QT。

 
  在我看來，如果你正在開發純C的API，這是有道理的。確保所有公共符號符合此唯一命名約定是另一個令人頭痛的問題。如果你正在使用C ++，那么你應該只在命名空間中對API功能進行分組，讓編譯器為你完成繁重的任務。

 
  我還強烈建議你使用嵌套命名空間來進行功能分組或將公共API與內部API分開。一個很好的例子是Boost庫，它們可以自由地使用嵌套的命名空間。例如，在根“boost”命名空間內，boost :: variant包含Boost Variant API的公共符號，boost :: detail :: variant包含該API的內部詳細信息。

錯誤＃2：在你的公共API頭的全局范圍中包含“using namespace”

為什么這是一個錯誤？

 
  這將導致被引用命名空間中的所有符號在全局命名空間中變得可見，并首先抵消掉使用命名空間的好處。

 
另外：

• 頭文件的使用者不可能撤消命名空間包含，因此他們被迫使用決策來使用你的命名空間，這是不可取的。
• 它極大地增加了命名空間首先要解決的沖突的可能性。
• 當引入新版本的庫時，程序的工作版本可能無法編譯。如果新版本引入的名稱與應用程序正在從另一個庫使用的名稱沖突，則會發生這種情況。
• 代碼中的“using namespace”部分從包含頭部的代碼中出現的那一點開始生效，這意味著在此之前出現的任何代碼都可能與該點之后出現的任何代碼區別對待。

 
如何解決這個問題？

• 1.盡量避免在頭文件中放置任何使用的命名空間聲明。如果你需要一些名稱空間對象來編頭文件，請在頭文件中使用完全限定名稱（例如std :: cout，std :: string）。

//File:MyHeader.h:
class MyClass
{   
private:
    Microsoft::WRL::ComPtr _parent;
    Microsoft::WRL::ComPtr _child;
}

• 2.如果上面的建議＃1導致代碼混亂太多 - 將“using namespace”用法限制在頭文件中定義的類或命名空間內。 另一個選擇是在頭文件中使用范圍別名，如下所示。

  //File:MyHeader.h:
  class MyClass
  {
  namespace wrl = Microsoft::WRL; // note the aliasing here !
  private:
  wrl::ComPtr _parent;
  wrl::ComPtr _child;
  }

  有關與C ++頭文件相關的其他問題，請參閱帖子“十大C ++頭文件錯誤以及如何修復它們”（https://www.acodersjourney.com/top-10-c-header-file-mistakes-and-how-to-fix-them/）。

 
 
 
more to read at https://mp.weixin.qq.com/s/Yyno5VNHr88BaQvMoZafVA