API 設計的一致性

像 naming、argument 順序、standard pattern 的使用、memory model、exception 的使用、error handling 等等,如果設計上有一致性,使用者較容易使用。保有一致性時,使用者可以輕易透過原本的理解認知推測新功能或其他部分如何使用。

在設計 C++ API 上,如果跟 standard library 保有相同的模式與規則也會讓 API 易於使用,畢竟大家都會用 standard library 啊!

雖然這篇標題是說 API 的設計,但小至 class 跟 function 也是有類似的觀念啊~

舉個 argument 不一致的例子:fscanf()fgets(),它們分別長這樣:

int fscanf(FILE* stream, const char* format, ...);
char* fgets(char* str, int num, FILE* stream);

兩個類似的 function,FILE* stream 參數卻是一個在第一個、一個在最後一個,讓我太久沒用就得回頭瞄一下文件……