C++ 中不容忽視的API 錯誤設(shè)計

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

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

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

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

為什么這是一個錯誤？

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

 
例如：讓我們考慮一個非常簡單的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符號添加一個唯一的前綴。如果遵循此約定，我們將調(diào)用我們的類“l(fā)vector”而不是“vector”。此方法用于OpenGL和QT。

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

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

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

為什么這是一個錯誤？

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

 
另外：

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

 
如何解決這個問題？

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

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

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

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

  有關(guān)與C ++頭文件相關(guān)的其他問題，請參閱帖子“十大C ++頭文件錯誤以及如何修復(fù)它們”（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